sagexx_ug (Раздаточные материалы)

Sage++A Class library for BuildingFortran 90 and C++ Restructuring ToolsNovember 1993cCopyright Please report any bugs you encounter in Sage++ to sage-bugs@cica.indiana.eduChapter 1: Introduction11 Introduction1.1 Aims and ObjectivesSage++ is an attempt to provide an object oriented toolkit for building program transformationsystems for Fortran 77, Fortran 90, C and C++ languages. Sage++ is intended to be used byresearchers interested in building parallelizing compilers, performance analysis tools, and sourcecode optimizers. It is designed as an open C++ class library that provides the user with a set ofparsers, a structured parse tree, a symbol and type table and access to programmer annotationsembedded in the source text.

The heart of the system is a set of functions that allow the toolbuilder complete freedom in restructuring the parse tree and a mechanism (called unparsing) togenerating new source code from the restructured internal form.The library is organized as a class hierarchy that provides access to the parse tree, symbol tableand type table for each le in an application project. There are ve basic families of classes in thelibrary Project and les, Statements, Expressions, Symbols and Types.1.2 HistorySage++ is based on an older system called Sigma (faust) which was, in turn, based on the Blazecompiler designed by Piyush Mehrotra in 1984. In its original form, Sigma was a tool kit forprogram restructuring that was accessed through the EMACS text editor (sigmacs).

The primaryadvantage of EMACS is that it has powerful, built-in programming system, ELISP, that allows itto be highly customized. Tool builders were able to call Sigma operations from ELISP code andinteractively restructure programs.Because many potential users were interested in building \stand alone" tools (not linked toEMACS), we designed an C function interface to the Sigma system, called Sigma II (sigma), whichprovided a high level view of the \data base" consisting of the parse trees of the source code andthe associated data dependence information.

Because the underlying data structures generated bythe parsers are very complex and awkward to use, Sigma II provided a level of abstraction thatallowed the tool builder to work in terms of source program units like statements and expressionsrather than the \low level" bit elds and linked lists of the internal structures. About the sametime a group at the University of Rennes and IRISA in France, designed a Sigma \ToolBox"that provided access to more powerful transformations and users annotations in the source code.Though the ToolBox was more powerful, it also required more knowledge of the underling parserdata structures.The design of Sage++ is based on the IRISA ToolBox, but it provides an additional level ofabstraction similar to, but more exible than the Sigma II interface.

One important dierencebetween Sage and Sigma is the treatment of data dependances and control ow information.Chapter 1: Introduction2The Sigma System, has a built-in control ow and data dependence analysis package. Whilethis analysis system has many advanced features, such as full symbolic analysis and rudimentaryinterprocedural capabilities, it was also limited in scope and hard to use. What was more important,it was imbedded at the lowest level of software and written in terms of the parser data structures.Consequently it was nearly impossible to modify by users wishing to experiment with more recentadvances in data dependence analysis theory.In Sage++ it has been decided to add the control ow structures and data dependence analysisprimitives on top of the user level class library. In this way, they can be easily modied or extendedby the tool user.

This aspect of Sage++ is not yet complete.1.3 OverviewIn this section we provide an overview of the Sage++ library. There are ve basic familiesof classes in the library: Projects and Files which correspond to source les in a multi sourceapplication project, Statements which correspond to the basic source statements in Fortran90, Cand C++, Expressions which are contained within statements, Symbols which are the basic userdened identiers, and Types which are associated with each identier and expression.In Sage++, program parsing and program analysis and restructuring are divided into two phases.Application projects in Fortran77, Fortran90, C and C++ are rst parsed, one le at a time toproduce a machine independent binary internal format called a .dep le. For example, given aapplication with source les `Main.f', `Subs.f', `c++funs.C', `cfuns.c' one invokes the Fortranparser cfp or the C parser pc++ to generate the corresponding .dep les.

Finally the user builds aproject le, `MyProject.proj' which lists each of the .dep les, one per line. In this example, the.proj le isMain.depSubs.depc++funs.depcfuns.depThe source language type is encoded within the .dep le. It should be noted that the .dep leis a complete translation of the source including comments and the original source, up to line andcolumn positions of tokens can be regenerated.The purpose of the project le is so that it is possible to exploit interprocedural analysis.Chapter 1: Introduction31.4 LimitationsSage++ has proven to be a powerful tool for our compiler prototyping experiments, but it stillhas a number of important limitations. The most important of these is that it is not easy for usersto add language extensions to Fortran or C to the system.

In principle this is not dicult. To adda new statement to the language one must extend the parser which is based on a the GNU Bisonversion of YACC. A new node type must be added to the internal form and a corresponding subclassadded to the Sage++ hierarchy. the unparser module, which is table driven must be extended torecognize this new node. While we have done this several times (we have added some of the PCFextensions to Fortran and extended C++ to dene our pC++ language (pC++)), it is not an easytask because it requires a complete understanding of the internal parser structures.Chapter 2: Projects and Files42 Projects and FilesA project is a group of parsed source les (.dep les) making up a program that is to bemanipulated by sage.

Sage can only deal with one project at a time (?).Ondisk, a project is represented as a le with name ending in .proj, containing a list of names of thecomponent .dep les, one le name per line.A le is one of the parsed source les in aproject.Each .dep le contains a parse tree. The root of the tree for a le iscalled the global node and its immediate children are the top level denitions and functions in theles. The le also contains a symbol table and type table. Refer to the overview for more detailsabout .dep les.2.1 SgProjectRepresents the les in the current project, for all languages.class SgProject {public:SgProject(char * proj_file_name);intnumberOfFiles();SgFile & file(int i);char *fileName(int i);intFortranlanguage();intClanguage();voidaddFile(char * dep_file_name);voiddeleteFile(SgFile * file);};SgProject is used in the following places in the example programs: see [Restructure - addStuToProgram], page 135 see [Restructure - main], page 139 see hundenedi [Instrument], page hundenedi see [Instrument - InitSymbols], page 140 see [Instrument - InitFunctionTable], page 141 see [Instrument - FInitialize], page 143 see [Instrument - ProjectUnparse], page 144Chapter 2: Projects and Filesseeseeseeseeseeseeseeseeseesee5[Instrument - FAnalyze], page 145[Instrument - CAnalyze], page 154[Instrument - CInitSymbols], page 155[Instrument - CInitialize], page 155[Instrument - OpenProject], page 157[Expand Syntax - CAnalyze], page 167[Expand Syntax - ProjectUnparse], page 168[Expand Syntax - main], page 168[Dump Info - ProjectUnparse], page 169[Dump Info - main], page 185Member Functions:SgProject(char * proj le name)Sage is initialized by instantiating an SgProject with this constructor.`proj_file_name' is a string containing the name of the .proj le that corresponds to the programto be manipulated.int numberOfFiles()Returns the number of les in the project.SgFile & le(int i)Returns a reference to the `i'th le in the project.char * leName(int i)Returns the name of the `i'th le in the project.int Fortranlanguage()Returns nonzero if every le in the project is a Fortran le.int Clanguage()Returns nonzero if at least one le in the project is not a Fortran le.void addFile(char * dep le name)Currently unimplemented.void deleteFile(SgFile * le)Currently unimplemented.Chapter 2: Projects and Files6SgProject UsageTypical usage of SgProject is as in the following example:#include "sage++user.h"main(){SgProject P("myproject.proj"); // opens and initializes projectfor(int i = 0; i < P.numberOfFiles(); i++){printf(" file is %s\n", P.fileName(i)");DoSomethingTo(P.file(i));};}Here's another one:#include <stdio.h>#include <GetOpt.h>#include "sage++user.h"intmain (int argc, char **argv){GetOpt getopt (argc, argv, "i:o:");SgProject *project;int option_char;char *ifile, *ofile;while ((option_char = getopt ()) != EOF)switch (option_char){case 'i': ifile = getopt.optarg; break;case 'o': ofile = getopt.optarg; break;case '?': fprintf (stderr,"usage: %s [i<input-proj> o<unparsed-file>]\n", argv[0]);}project = new SgProject (ifile);}/* do something with the project */2.2 SgFileThis class provides access to the local symbol and type tables, and the top level denitions, inthe .dep le it corresponds to.Represents les, for all languages.Chapter 2: Projects and Filesclass SgFile {public:PTR_FILE filept;SgFile(char* file_name);intlanguageType();voidsaveDepFile(char *dep_file);voidunparse(FILE *filedisc);voidunparsestdout();SgStatement *SgStatement *intSgStatement *intmainProgram();functions(int i);numberOfFunctions();getStruct(int i);numberOfStructs();SgStatement *SgSymbol *SgType *SgExpression *firstStatement();firstSymbol();firstType();firstExpression();SgExpression *SgStatement *SgStatement *SgSymbol *SgType *SgExpressionWithId(int i);SgStatementWithId( int id);SgStatementAtLine(int lineno);SgSymbolWithId( int id);SgTypeWithId( int id);};SgFile is used in the following places in the example programs: see [Restructure - addStuToProgram], page 135 see [Restructure - main], page 139 see [Instrument - InitSymbols], page 140 see [Instrument - InitFunctionTable], page 141 see [Instrument - ProjectUnparse], page 144 see [Instrument - FAnalyze], page 145 see [Instrument - ListCollections], page 153 see [Instrument - ListCollectionInstances], page 153 see [Instrument - ListCollectionInvocations], page 153 see [Instrument - CAnalyze], page 154 see [Instrument - CInitSymbols], page 1557Chapter 2: Projects and Filesseeseeseeseeseeseeseeseeseeseeseesee8[Instrument - IsFortran], page 158[Instrument - IsC], page 158[Expand Syntax - ExpandSyntax], page 162[Expand Syntax - Init], page 166[Expand Syntax - CAnalyze], page 167[Expand Syntax - ProjectUnparse], page 168[Expand Syntax - main], page 168[Dump Info - ProjectUnparse], page 169[Dump Info - classifyStatements], page 170[Dump Info - classifyExpressions], page 181[Dump Info - classifySymbols], page 185[Dump Info - main], page 185Member Functions:SgFile(char* le name)Provides a way to generate a new SgFile which can be added to the project.

(? How?)int languageType()Returns CSrc (for C) or ForSrc (for Fortran).void saveDepFile(char *dep le)Saves the (internal representation of the) le as a .dep le with lename dep_file.void unparse(FILE *ledisc)Unparses the (internal representation of the) le and saves the result in the le with le descriptorfiledisc.void unparsestdout()Unparses the (internal representation of the) le to standard output.SgStatement * mainProgram()Returns the statement in the le at which the main program is located, or NULL if the mainprogram is not located in this le.SgStatement * functions(int i)Returns the ith function in the le.int numberOfFunctions()Returns the number of functions in the le.Chapter 2: Projects and Files9SgStatement * getStruct(int i)Returns the ith structure (? or class or union?) in the le.int numberOfStructs()Returns the number of structures in the le.SgStatement * rstStatement()Returns the rst statement in the le.SgSymbol * rstSymbol()Returns the rst symbol in the le's symbol table.SgType * rstType()Returns the rst type in the le's type table.SgExpression * rstExpression()Returns the rst expression in the le.SgExpression * SgExpressionWithId(int i)Returns the expression in the le with id i.SgStatement * SgStatementWithId( int id)Returns the statement in the le with id id.SgStatement * SgStatementAtLine(int lineno)Returns the statement at line i in the le.SgSymbol * SgSymbolWithId( int id)Returns the symbol in the le with id id.SgType * SgTypeWithId( int id)Returns the type in the le with id id.SgFile UsageNormally, you won't instantiate an SgFile yourself; you'll instantiate a project, then access theles in the project through the le() member of SgProject.There are two ways to traversea le.