Home

ROSE Compiler Framework

1. 11 5 2 LiveDead Variable Functions to convert program point to Generator and KILL set For liveness analysis e Kill s variables being defined in sj e Gen s variables being used in s OUT IN KILL GEN 7 http en wikibooks org wiki liveness 20analysis 56 Transfer Function e OUT is initialized to be IN set e transfer function will apply KILL GEN class LiveDeadVarsTransfer public IntraDFTransferVisitor LiveVarsLattice liveLat the result of this analysis bool modified Expressions that are assigned by the current operation std set lt SgExpression gt assignedExprs KILL set Variables that are assigned by the current operation std set lt varID gt assignedVars Variables that are used read by the current operation std set lt varID gt usedVars GEN set public LiveDeadVarsTransfer const Function amp f const DataflowNode amp n NodeState amp s const std vector lt Lattice gt amp d funcSideEffectUses fseu_ IntraDFTransferVisitor f n s d indent Y liveLat dynamic_cast lt LiveVarsLattice gt dfInfo begin modified false fseu fseu_ if liveDeadAnalysisDebugLevel gt 1 Dbg dbg lt lt indent lt lt liveLat lt lt liveLat gt str indent lt lt std endl Make sure that all the lattice is initialized liveLat gt initialize bool finish operationg on different AST nodes void visit SgExpression
2. Optional detailed description starts here Option 2 kk brief Brief description Brief description continued Optional detailed description starts here Single line comment followed by multiple line comments You may extend an existing single line comment with a multiple line comments Option 1 or 2 For example Brief description kk 108 Functions Detailed description starts here TODO provide a full combined example 16 11 Functions Rules e Except for simple functions like getXX and setXX all other functions should have at least one line comment to explain what it does e Avoid global functions and global variables Try to put them into a namespace e A function should not have more than 100 lines of code Please refactor big functions into smaller separated functions e Limit the unconditional printf so your translator will not print hundreds lines of unnecessary text output when processing multiple input files e Use an if condition to control printf for debugging purposes such as if SgProject get_verbose gt 0 e The beginning part of the function should try to do sanity check for the function parameters 16 12 Comments Rules e Please follow Doxygen style comments e Please explain in sufficient detail how your function works and the steps in the algorithm e Reviewers will read your commented information to understand your algorithm and then read
3. 11 12 TODO e Hard to use the generated lattices since many temporary expression objects are generated in lattices But often users do not care about them constant propagation pointer analysis to see the problem go to build64 tests roseTests programAnalysisTests generalDataFlowAnalysisTests run make check see the dot graph dump of an analysis run sh test_ptr4 C_main_0x2b41e651c038_ cfg dot 77 12 Program Optimizations ROSE provides the following program optimizations and tranformations e loop transformation including loop fusion fisson unrolling blocking loop interchange etc e inlining e outlining e constant folding e partial redundancy elimination 79 13 ROSE Projects This page serves as a quite guide about what the major directories under rose projects are Parsing e pragmaParsing An example translator using the parsing building blocks provided by ROSE to parse pragmas Translations e autoTuning a project to use ROSE s parameterized translators to facilitate empirical tuning or autotuning e DataFaultTolerance a project to use source to source translation to make application resilient to memory faults e extractMP Skeleton extract MPI communication skeletons e Fortran_to_C A Fortran to C language translator Static Analysis e compass a static analysis tool to find errors in applications Dynamic Analysis e RTED runtime error detection using compiler instrumentation of libr
4. 22 1 make check rules we leverage make check rules to do internal testing 22 1 1 check exist status of pipeline command In bash scripting we can use pipelines as follows e commandl command2 the output of each command in the pipeline is connected to the input of the next command each command is executed in its own subshell exit status the last command s exit status To catch any command s return code please use PIPESTATUS 0 For example Using pipeline will only return the last command folds status we add a test to catch the first command s return status autoPar c srcdir 0 0 c fold gt o out test PIPESTATUS 0 0 22 2 Benchmarks The software used by the ROSE s Jenkins include e SPEC CPU 2006 benchmark a subset is supported for now e SPEC OMP benchmark a subset is supported for now e NAS parallel benchmark developed by NASA Ames Research Center Both C cus tomized version and OpenMP versions are used e Plum Hall C and C Validation Test Suites a subset is supported for now e Jt Java conformance testing http modena us 1 http jenkins ci org 2 http en wikibooks org wiki RO0SE 20Compiler 20Framework 2FSPEC 20CPU 42020067 20benchmark 3 http en wikipedia org wiki NAS_Parallel_Benchmarks 183 Testing 22 3 Modena Jt Test Suite 1 Clone the Modena test suite repository git clone ssh rose dev rose git modena 2 Autotools
5. Here are a few guidelines in the event you need to reject someone s submission or ask them to clean up their work 1 Focus your comments on the code and any objectively observed behavior not moti vations for example don t state or imply assumptions about motivating factors like whether the developer was just too lazy or stupid to do things right 2 Be empathetic and kind Recognize that the developer has probably put a lot of work in their idea and thank them for their contribution if you feel comfortable and sincere in doing so and try to muster the comfort and sincerity Most importantly put yourself in their shoes and say something that indicates you ve done so 3 Help them schedule their work If their idea is a not yet kind of idea try to recommend the best way you know of to get their idea on a backlog i e the backlog most likely to eventually get revisited 4 Let them know where they can appeal your decision For example if the contributor doesn t have a history of being disruptive or dense invite them to discuss the issue on wikitech l 5 Be clear Don t sugarcoat things so much that the central message is obscured 122 Who should review what 6 Most importantly give the feedback quickly While tactful is better and you should learn from past mistakes you can always apologize for a poorly delivered comment with a quick followup Don t just leave negative feedback to someone else or hope they aren t pers
6. The ROSE project uses a workflow that automates the central principles of continuous integration in order to make integrating the work from different developers a non event Because the integration process only integrates with ROSE the changes that passes all tests we encourage all developers to stay in sync with the latest version A high level overview of the development model used by ROSE developers e Step 1 Taking advantage of the distributed source code repositories based on git each developer should first clone his her own repository from our central git repository or its mirrors clones forks e Step 2 Then a feature or a bugfix can be developed in isolation within the private repository He can create any number of private branches Each branch should relate to a feature that this developer is working on and be relatively short lived The developer can commit changes to the private repository without maintaining an active connection to the shared repository e Step 3 When work is finished and locally tested he can pull the latest commits from the central repo s master branch e Step 4 He then can push all accumulated commits within the private repository to his branch within the shared repository We create a dedicated branch within the central repository for each developer and establish access control of the branch so only an authorized developer can push commits to a particular branch of the shared repository e Step 5 6 autom
7. e good example fileName h What should be avoided e start with capitalization e bad example using underscore file_name h Bad file name e functions h e file name h References e http geosoft no development cppstyle html cppstyle html Files e A couple good points http www records ncder gov erecords filenaming_ 20080508 _final pdf 16 8 2 Line Length e File content should be kept within 80 columns 80 columns is a common dimension for editors terminal emulators printers and debuggers and files that are shared between several people should keep within these constraints It improves readability when unintentional line breaks are avoided when passing a file between programmers If you write a tutorial with more than 80 columns it is likely to not fit on the page This effectively makes the tutorial useless without having to go into the code base itself 16 8 3 Indentation Avoid tabs for your code indentation except in cases where tabs t are required e g Makefiles 2 or 4 spaces is recommended for code indentation for i 0 i lt nElements i 103 Coding Standard ali 0 Indentation of 1 is too small to emphasize the logical layout of the code Indentation larger than 4 makes deeply nested code difficult to read and increases the chance that the lines must be split 16 8 4 Characters Special characters like TAB and page break must be avoided These characters are bound to cause pro
8. e if BOTTOM lt x lt y lt TOP then x is a conservative approximation of y e g x is a superset 24 10 1 e g liveness analysis bitvector for all variables x_1 x_2 x_n First step design the lattice values e top value empty set initial value knowing nothing e bottom value all set x_1 x_2 x_n max possible value knowing every variable is live n 3 3 variable case a flow value gt a set of live variable at a point S v1 v2 v3 value set 2 3 empty v1 v2 v3 v1 v2 v1 v3 v2 v3 v1 v2 ve Design lattice e top value best case none live T top e bottom value worst ase all live v1 v2 v3 195 Lattices Design meet set Union Or operation bring the value down to the bottom context insensitive e design partial order lt gt D In between a partial order inferior conservative solutions are lower on the lattice Top vi v2 v3 x x v1 v2 v1 v3 v2 v3 v1 v2 v3 Bottom Flow function F fn X Genn U X Killn Vn 24 10 2 reaching definition Value 2 n n number of all definitions top empty set knowing nothing initial value bottom all set all definitions are reaching definition Meet operation set union bring down the levels of values from unknowing to knowing 196 25 C Programming ROSE is written in C Some users have suggested to mention the major C program ming technique
9. void visit SgInitializedName void visit SgReturnStnt void visit SgExprStatement void visit SgCase0ptionStmt void visit SgIfStmt void visit SgForStatement void visit SgWhileStmt void visit SgDoWhileStmt Helper transfer function focusing on handling expressions live dead variable analysis LDVA expression transfer transfer functions for expressions Nisits live expressions helper to LiveDeadVarsTransfer class LDVAExpressionTransfer public ROSE_VisitorPatternDefaultBase LiveDeadVarsTransfer amp ldva public Plain assignment lhs rhs set GEN read used and KILL written assigned sets void visit SgAssign0p sgn ldva assignedExprs insert sgn gt get_lhs_operand If the lhs of the assignment is a complex expression i e it refers to a variable that may be live OR if is a known expression that is known to may be live THIS CODE ONLY APPLIES TO RHSs THAT ARE SIDE EFFECT FREE AND WE DON T HAVE AN ANALYSIS FOR THAT YET if isVarExpr sgn gt get_lhs_operand isVarExpr sgn gt get_lhs_operand e 87 Generic Dataflow Framework liveLat gt isLiveVar SgExpr2Var sgn gt get_lhs_operand ldva used sgn gt get_rhs_operand 11 5 3 Call Stack gdb bt 0 LDVAExpressionTransfer visit this 0x7ffffff cea0 sgn 0xa20320 at sourcetree src midend pro gramAnalysis genericDataflow simpleAnalyses liveDe
10. Code using the filter function int main int argc char argv SgProject project frontend argc argv initAnalysis project LiveDeadVarsAnalysis ldva project ldva filter gfilter set the filter to be your own one UnstructuredPassInterDataflow ciipd_ldva amp ldva ciipd_ldva runAnalysis 11 7 Analysis Driver Key function bool IntraUniDirectionalDataflow runAnalysis const Function amp func NodeState fState bool analyzeDueToCallers set lt Function gt calleesUpdated analysis dataflow C Basic tasks run the analysis by e initialize data flow state lattices and other information e walk the CFG find descendants from a current node e call transfer function 59 Generic Dataflow Framework 11 7 1 Class Hierarchy e Analysis gt IntraProceduralAnalysis gt IntraProceduralDataflow gt IntraUnitDataflow gt IntraUniDirectionalDataflow INTERESTING level gt IntraBWDataflow gt LiveDead VarsAnalysis class Analysis an empty abstract class for any analysis class IntraProceduralAnalysis virtual public Analysis analysis analysis h any intra procedural analysis data flow or not protected InterProceduralAnalysis interAnalysis public void setInterAnalysis InterProceduralAnalysis interAnalysis connection to inter procedural analysis virtual bool runAnalysis const Function amp func NodeState state 0 run this per function NodeState stores
11. InfiniteLattice meetResult InfiniteLattice itN gt second gt meet itC gt second InfiniteLattice meetResult dynamic_cast lt InfiniteLattice gt itN gt copy Dbg dbg lt lt itN lt lt dynamic_cast lt InfiniteLattice gt itN gt str lt lt endl Dbg dbg lt lt itC lt lt dynamic_cast lt InfiniteLattice gt itC gt str lt lt endl meetResult gt meetUpdate itC Dbg dbg lt lt meetResult lt lt meetResult gt str lt lt endl Widen the resulting meet modified dynamic_cast lt InfiniteLattice gt itN gt widenUpdate meetResult delete meetResult 67 Generic Dataflow Framework if analysisDebugLevel gt 1 if modified Dbg dbg lt lt Next node s in data modified Adding lt lt endl int j 0 for itN nextNodeState begin itN nextNodeState end itN j Dbg dbg lt lt Propagated Lattice lt lt j lt lt n lt lt itN gt str lt lt endl else Dbg dbg lt lt No modification on this node lt lt end1 return modified 11 7 6 stop condition class IntraUniDirectionalDataflow public IntraUnitDataflow public protected propagates the dataflow info from the current node s NodeState curNodeState to the next node s NodeState nextNodeState return true if any state is modified bool propagateStateToNextNode const std vector lt Lattice
12. Read these tips and guidelines before sending a request for code review 17 4 1 Coding Standards Please go to Coding Standard for the complete guideline Here we only summary some key points Your code should be written in a way that makes it easily maintainable and reviewable https enterprise github com dashboard http www redmine org http code google com p gerrit Chapter 16 on page 91 oR Wb 117 Code Review Process write easy to understand code avoid using exotic techniques which nobody can easily understand add sufficient documentation source code comments README etc to aid the under standability of your code your documentation should cover e why do you do this motivation e how do you do it design and or algorithm e where are the associated tests works as expected before submission of your code for review make sure e you have merged with the latest central repository s master branch without conflicts e your working copy can pass local tests via make make check and make distcheck e you have fixed all compiler warnings of your code whenever possible submit a logical unit of work one or more commits something coherent like a bug fix an improvement of documentation an intermediate stage for reaching a big new feature balance code submissions with a good ratio of lines of code and complexity of code A good balance needs to be achieved to make the reviewer s life easier e t
13. We added the necessary logic to make the function complete tested it to verify its correctness and then called it a day Phew Not so bad right 20 9 How to add a new project directory Most code development that is layered above the ROSE library starts out its life as a project in the projects directory Some projects are eventually refactored into the ROSE library once they mature This chapter describes how one adds a new project to ROSE 20 9 1 Required Files A ROSE project encapsulates a complete program or set of related programs that use the ROSE library Each project exists as a subdirectory of the ROSE projects directory and should include files README rose config Makefile am and any necessary source files scripts tests etc 171 How tos The README should provide an explanation about the project purpose algorithm design implementation etc e The rose config integrates the project into the ROSE build system in a manner that allows the project to be an optional component they can be disabled renamed deleted or withheld from distribution without changing any ROSE configuration files Most older projects are lacking this file and are thus more tightly coupled with the build system e The Makefile am serves as the input to the GNU automake system that ROSE employs to generate Makefiles e Each project should also include all necessary source files documentation and test cases 20 9 2 Sett
14. e Not every poset is a lattice greatest lower bounds and least upper bounds need not exist in a poset 24 4 Infinite vs Finite lattices e Infinite An infinite lattice does not contain an 0 bottom or 1 top element even though every pair of elements contains a greatest lower bound and a least upper bound on the entire underlying set By the definition of unbounded or infinite sets we know that given X an unbounded set given any x in X we can find an x that is greater than x under some ordering in this case the lattice Similarly for greatest lower bounds e a finite bounded lattice the underlying set itself has a greatest lower bound and a least upper bound For now we will call the greatest lower bound 0 and the least upper bound 1 e if ax x for all x in L then a is the O element of L L recall that this is a unique element e if a gt x for all x from L then a is the 1 element of L T Meet A is a binary operation such that a A b take the greatest lower bound of the set this is guaranteed by the definition lattice Similarly Join V returns the least upper bound of the set guaranteed to exist by the definition of a lattice To recap a lattice L is a triple X A V composed of a set a Meet function and a Join function Properties of Meet and A e We refer to the V as V and the A as J 192 Example Bit vector Lattices e Closure If x and y belong to L then there exists a unique z and a unique w from L such
15. gt 0N Aa http rosecompiler org ROSE_Tutorial ROSE Tutorial pdf http github com rose compiler rose commit f4d5292dadla68ee13cd9b38834efe4813db92ec http en wikibooks org wiki ROSE 20Compiler 20Framework 2FConstant 20Propagation http en wikibooks org wiki ROSE 20Compiler 20Framework 2FPointer 20Analysis 49 Generic Dataflow Framework 11 3 Function nodeState and FunctionState Function and nodeState are two required parameters to run data flow analysis They are stored together inside FunctionState functionState h functionState h genericDataflow cfgUtils CallGraphTraverse h 11 3 1 function An abstraction of functions internally connected to SgFunctionDeclaration decl declared in src midend programAnalysis genericDataflow cfgUtils CallGraphTraverse h constructors e Function Function string name based on function name e Function Function SgFunctionDeclaration sample core constructor e Function Function SgFunctionDefinition sample CGFunction cgFunc call graph function Function func cgFunc 11 3 2 NodeFact any information related to a CFG node e It has no dataflow s IN OUT concept e not meant to evolve during the dataflow analysis class NodeFact public printable public returns a copy of this node fact virtual NodeFact copy const 0 11 3 3 NodeState Store information about multiple analyses and their corresponding lattices for a given node CFG node src midend
16. 1 m_ctorInitializer 0 m_default 1 m_defaultColor 1 m_edge 1 m_emptySymbolTable 0 m_expression 0 m_fileInfo 1 m_frontendCompatibility 0 m_symbol 0 m_type 0 m_variableDeclaration 0 m_variableDefinition 0 m_noFilter 0 011 011 011 011 011 011 011 011 011 011 011 011 011 011 011 011 011 show this help message Disable Disable Disable Disable Disable Disable Disable Disable Disable Disable Disable Disable Disable Disable Disable Disable Disable or or or or or or or or or or or or or or or or or 27 ROSE tools 6 4 call graph generator Command line buildCallGraph c yourprogram cpp 6 5 Control flow graph generator Command line virtualCFG c yourprogram c 6 6 TODO 6 6 1 refactor the tool translators Refactor the tools into a dedicated rose tools directory So they will always be built and available by default with minimum dependency on other things like which languages are turned on or off when applicable of course Our current idea is we should separate translators used as examples or tutorials AND translators used for creating end user tools e For tutorial translators they should NOT be installed as tools by default Their purpose is to be included in Manual or Tutorial pdf files to illustrate something to
17. Boost becomes the required software to use ROSE e But Boost library has its disadvantages hard to install just see how many boost issues on our public mailing list lack of backward compatibility codes using older version of boost break on new versions huge header files with complex C templates slowing down compilation or even breaking some compilers e We still have internal debates about what to do with Boost It is often a painful and emotional process Solution e Introducing big software dependency very carefully Or you will get stuck easily e At least ask people who advocate for new software dependency to be responsible for maintaining it for 5 years and providing an option to turn it off at the same time 21 6 Create Exacting Tests Early and Often Lesson e A developer created tests that were too broad mostly because they were included late in development This led to passes that should not have passed that is passing all tests even though the code had been broken Solution 180 Keep Code Readable While Coding e Make sure that tests check results carefully This is made much easier by making sure your functions have precisely ONE intention E g if you need to transform data and operate on the transformed data split the transformation and the operation into two functions at least 21 7 Keep Code Readable While Coding Lesson e A developer wrote code without commenting initially then came back to
18. GPL clearly explains that there is no warranty for this free software For both users and authors sake the GPL requires that modified versions be marked as changed so that their problems will not be attributed erroneously to authors of previous versions Some devices are designed to deny users access to install or run modified versions of the software in side them although the manufacturer can do so This is fundamentally incompatible with the aim of protecting users freedom to change the software The systematic pattern of such abuse occurs in the area of products for individuals to use which is precisely where it is most unacceptable Therefore we have designed this version of the GPL to pro hibit the practice for those products If such prob lems arise substantially in other domains we stand ready to extend this provision to those domains in future versions of the GPL as needed to protect the freedom of users Finally every program is threatened constantly by software patents States should not allow patents to restrict development and use of software on general purpose computers but in those that do we wish to avoid the special danger that patents applied to a free program could make it effectively proprietary To prevent this the GPL assures that patents cannot be used to render the program non free The precise terms and conditions for copying dis tribution and modification follow TERMS AND CONDITIONS 0
19. NodeState state to be implemented by InitDataflowState virtual void visit const Function amp func const DataflowNode amp n NodeState amp state 0 bool UnstructuredPassIntraAnalysis runAnalysis const Function amp func NodeState state DataflowNode funcCFGStart cfgUtils getFuncStartCFG func get_definition DataflowNode funcCFGEnd cfgUtils getFuncEndCFG func get_definition if analysisDebugLevel gt 2 Dbg dbg lt lt UnstructuredPassIntraAnalysis runAnalysis function lt lt func get_name getString lt lt n iterate over all the nodes in this function for VirtualCFG iterator it funcCFGStart it VirtualCFG dataflow end it DataflowNode n it The number of NodeStates associated with the given dataflow node int numStates NodeState numNodeStates n The actual NodeStates associated with the given dataflow node const vector lt NodeState gt nodeStates NodeState getNodeStates n Visit each CFG node for vector lt NodeState gt const_iterator itS nodeStates begin itS nodeStates end itS visit func n itS return false ae derived class provide link to a concrete analysis and visit implementation 62 Analysis Driver class InitDataflowState public UnstructuredPassIntraAnalysis IntraProceduralDataflow dfAnalysis link to the dataflow analysis to be initialized public InitDataflowState Int
20. Preserve any Warranty Disclaimers If the Modified Version includes new front matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document you may at your option designate some or all of these sections as invariant To do this add their titles to the list of Invariant Sections in the Modified Version s license notice These titles must be distinct from any other section titles You may add a section Entitled Endorsements provided it contains nothing but endorsements of your Modified Version by various parties for ex ample statements of peer review or that the text has been approved by an organization as the au thoritative definition of a standard You may add a passage of up to five words as a Front Cover Text and a passage of up to 25 words as a Back Cover Text to the end of the list of Cover Texts in the Modified Version Only one passage of Front Cover Text and one of Back Cover Text may be added by or through arrangements made by any one entity If the Document already includes a cover text for the same cover previously added by you or by arrangement made by the same entity you are acting on behalf of you may not add an other but you may replace the old one on explicit permission from the previous publisher that added the old one The author s and publisher s of the Document do not by this License give permission to use their names for publicity for or to
21. Sending error email to user llnl gov because their github master is non fast forwardable email details are omitted here fi done 18 8 TODO High priority e Add a pre screening job before manual code review kicks in the pre screening job can make sure the code to be reviewed will be compiled with minimum warning messages and with required make check rules to run tests e enable email notification for the final results of each test 131 Continuous Integration e incrementally add more compilation tests using external benchmarks to be integration tests e Initial two jobs spec cpu benchmark NPB Fortran benchmarks e Better integration with Github Enterprise e Avoid the Auto Push failure due to pending commits on private repo s master branch e Look into how others are doing this Github Jenkins integration e http www foraker com hudson github hooks e https wiki jenkins ci org display JENKINS Github Plugin Third Party software installed for testing in Jenkins e Yices http yices csl sri com e Download Yices1 the lasted version is better e untar the tarball package of yices then it is YICES_ INSTALL which is name like yices 1 0 34 Type with yices YICES_INSTALL with ROSE configure option e setup YICES_INSTALL lib into LD_LIBRARY_PATH for Linux and DYLD_ LIBRARY_PATH for mac users it is like add Boost lib into LD_LIBRARY_PATH 18 9 References e Files used to generate the figure feel free to a
22. Whoever contributes the most should has a little bit more weight to say Documentation We require major changes to be documented and reviewed before deployment Writing down things can help us clarify details and solicit wider comments instead of limited to face to face meeting 16 Coding Standard 16 1 What to Expect and What to Avoid This page documents the current recommended practice of how we should write code within the ROSE project It also serves as a guideline for our code review process New code should follow the conventions described in this document from the very beginning Updates to existing code that follows a different coding style should only be performed if you are the maintainer of the code The order of sections in coding standard follows a top down approach big things first then drill down to fine grain details 16 1 1 Six Principles We use coding standard to reflect the principal things we value for all contributions to ROSE e Documentation What are the commits about Is this reflected in commit messages README source comments or LaTex files within the same commits e Style Is the coding style consistent with the required and recommended formats Is the code clean and pleasant and easy to read Interface Does the code has a clean and simple interface to be used by users e Algorithm Does the code has sufficient comments about what algorithm is used Is the algorithm correct and efficient spa
23. You can have bigger numbers if your machine supports more concurrent processes Still the entire process will take hours to finish For most users building librose so should be enough for most of their work In this case just type 17 Installation make C src j4 4 6 make check Optionally you can type make check to make sure the compiled rose pass all its shipped tests This takes hours again to go through all make check rules within projects tutorial and tests directories To save time you can just run partial tests under a selected directory like the buildrose tests make C tests check j4 4 7 make install After make it is recommended to run make install so rose s library librose so headers rose h and some prebuilt rose based tools can be installed under the specified installation path using prefix 4 8 set environment variables After the installation you should set up some standard environment variables so you can use rose For bash the following is an example ROSE_INS home userx opt rose_installation_tree PATH PATH ROSE_INS bin LD_LIBRARY_PATH LD_LIBRARY_PATH ROSE_INS lib Don t forget to export variables export PATH LD_LIBRARY_PATH 4 9 try out a rose translator There are quite some pre built rose translators installed under ROSE_INS bin You can try identityTranslator which just parses input code generates AST and unparses it back to original
24. amp itP dfInfoPost end itAt itP j if analysisDebugLevel gt 1 Dbg dbg lt lt Meet Before Lattice lt lt j lt lt n lt lt xitA gt str lt lt endl Dbg dbg lt lt Meet After Lattice lt lt j lt lt n lt lt xitP gt str lt lt endl itP gt copy itA if analysisDebugLevel gt 1 Dbg dbg lt lt Copied Meet Below Lattice lt lt j lt lt n lt lt itB gt str lt lt endl TRANSFER FUNCTION IN KILL GEN if isSgFunctionCallExp sgn transferFunctionCall func n state boost shared_ptr lt IntraDFTransferVisitor gt transferVisitor getTransferVisitor func n state dfInfoPost sgn gt accept transferVisitor modified transferVisitor gt finish modified TRANSFER FUNCTION 11 7 5 propagate state to next meet Update This is prove to be essential to propagate information along the path Cannot commenting it out not sure about the difference between this step and the step before Meet Before Meet After 66 Analysis Driver meet Update is called here also Propagates the dataflow info from the current node s NodeState curNodeState to the next node s NodeState nextNodeState Returns true if the next node s meet state is modified and false otherwise bool IntraUniDirectionalDataflow propagateStateToNextNode const vector lt Lattice gt amp cu
25. and anything in between e initialization LiveDeadVarsAnalysis genInitState e creation transfer function e meet operation a member function of the lattice Example e liveness analysis the live variable set at the entry point of a CFG node e constant propagation lattice values from no information bottom gt unkown gt constant gt too much information conflicting constant values top blindly add all of that_arg s values into current lattice s value set void LiveVarsLattice incorporateVars Lattice that_arg retrieve a subset lattice information for a given expr This lattice may contain more information than those about a given expr Lattice LiveVarsLattice project SgExpression expr add lattice exprState information about expr into current lattice s value set default implementation just calls meetUpdate exprState bool LiveVarsLattice unProject SgExpression expr Lattice exprState 11 4 2 below above vs IN OUT The concept is based on the original CFG flow direction e above the incoming edge direction e below the outcoming edge direction IN and OUT depends on the direction of the problem forward vs backward e forward direction IN above lattice OUT below lattice e backward direction IN below lattice OUT above lattice 11 4 3 Common Utility Lattices the framework provides some pre defined lattices ready for use lattice h latticeFull h e BoolAndLattice 11 4 4 Liv
26. c For a Combined Work that displays copyright no tices during execution include the copyright notice for the Library among these notices as well as a ref erence directing the user to the copies of the GNU GPL and this license document d Do one of the following o 0 Convey the Minimal Corresponding Source under the terms of this License and the Cor responding Application Code in a form suitable for and under terms that permit the user to recombine or relink the Application with a modified version of the Linked Version to produce a modified Com bined Work in the manner specified by section 6 of the GNU GPL for conveying Corresponding Source o 1 Use a suitable shared library mechanism for linking with the Library A suitable mechanism is one that a uses at run time a copy of the Li brary already present on the user s computer sys tem and b will operate properly with a modified version of the Library that is interface compatible with the Linked Version e Provide Installation Information but only if you would otherwise be re quired to provide such information under section 6 of the GNU GPL and only to the extent that such information is necessary to install and execute a modified version of the Combined Work produced by recombining or relinking the Application with a modified version of the Linked Version If you use option 4d0 the Installation Information must accompany the Minimal Corresponding Source and Corresp
27. e many existing namespaces in ROSE already follow CamelCase as shown at link Note Leo I believe this should be more discussed with ROSE Compiler Framework ROSE APT 16 6 5 Types MUST be in mixed case starting with an uppercase letter as in SavingsAccount 9 http rosecompiler org ROSE_HTML_Reference namespaces html 10 http en wikibooks org wiki ROSE 20Compiler 20Framework 2FROSE 20API 98 Naming Conventions 16 6 6 Variables e Length variables with a large scope should have long names variables with a small scope can have short names Temporary variables used for temporary storage e g loop indices are best kept short A programmer reading such variables should be able to assume that its value is not used outside of a few lines of code Common scratch variables for integers are i j k m n Optionally you can use ii jj kk mm and nn which are easier to highlight when looking for indexing bugs e Case camelCase mixed case starting with lowercase letter as in functionDecl e Variables are purposely to start with lowercase letter as compared to upper case letter for Types So it is clear by looking at the first letter to know if a name is a variable or a type Booleans Negated boolean variable names must be avoided The problem arises when such a name is used in conjunction with the logical negation operator as this results in a double negative It is not immediately apparent what isNotFound me
28. funded to implement UPC in ROSE e roseupcc is located in ROSE projects UpcTranslation e Documented by 13 5 An Example UPC to C Translator Using ROSE of the ROSE manual 7 3 CUDA ROSE has an experimental connection to EDG 4 0 which helps us support CUDA To enable parsing CUDA codes please use the following configuration options enable edg version 4 0 enable cuda enable edg cuda Chapter 16 of ROSE User Manual has more details about this More details from Tristan on Sept 24 2012 e enable cuda option enable CUDA IR in ROSE IR preinclude e enable edg cuda option only apply to EDG it activates the EDG support in EDG 4 x actually I need to patch EDG 4 4 e When enable edg cuda is present we also need to have enable edg version 4 x x 0 3 e enable cuda is relevant for enable only cuda as the EDG which is usually distributed as binary edg options are targeting only 7 4 OpenCL 30 8 Abstract Syntax Tree Intermediate Representation The main intermediate representation of ROSE is its abstract syntax tree AST 8 1 Sanity Check We provide a set of sanity check for AST We use them to make sure the AST is consistent It is also highly recommended that ROSE developers add a sanity check after their AST transformation is done This has a higher standard than just correctly unparsed code to compilable code It is common for an AST to unparse correctly but then f
29. github com git git git Install all prerequisite packages needed to build git from source files assuming you already installed GNU tool chain with GCC compiler make etc sudo apt get install gettext zlibig dev asciidoc libcurl4 openssl dev cd git enter the cloned git directory make configure as yourself configure prefix usr as yourself make all doc as yourself make install install doc install html as root 23 3 Converting from a Subversion user If you re coming from a centralized system you may have to unlearn a few of the things you ve become accustomed to e For example you generally don t checkout out a branch from a central repo but rather clone a copy of the entire repository for your own local use e Also rather than using small sequential integers to identify revisions Git uses a cryp tographic hash SHA1 although in general you only need to ever write the first few characters of the hash just enough to uniquely identify a revision e Finally the biggest thing to get used to ALL work is done on local branches there s no such thing in the DSCM world as working directly on a central branch or checking your work directly into a central branch Having said that distributed revision control is a superset of centralized revision control and some projects including ROSE set up a centralized repository as a policy choice for sharing code between developers When
30. lt lt 1DF gt str lt lt endl 69 Generic Dataflow Framework Dbg dbg lt lt 1Ret Before lt lt 1Ret gt str lt lt endl 1DF gt unProject isSgFunctionCallExp n getNode lRet Dbg dbg lt lt 1DF After lt lt 1DF gt str lt lt endl 11 8 2 InterProceduralDataflow Inte rProceduralDataflow InterProceduralDataflow IntraProceduralDataflow intraDataflowAnalysis Int erProceduralAnalysis IntraProceduralAnalysis intraDataflowAnalysis NOTE cfgForEnd AND cfgForBeginning PRODUCE THE SAME SgFunctionDefinition SgNode BUT THE DIFFERENT INDEXES 1 0 FOR BEGINNING AND 3 FOR END AS SUCH IT DOESN T MATTER WHICH ONE WE CHOOSE HOWEVER IT DOES MATTER A WHETHER WE CALL genInitState TO GENERATE THE STATE BELOW THE NODE START OF THE FUNCTION OR ABOVE IT 0 END OF THE FUNCTION THE CAPABILITY TO DIFFERENTIATE THE TWO CASES NEEDS TO BE ADDED TO genInitState 1 AND WHEN IT IS WE LL NEED TO CALL IT INDEPENDENTLY FOR cfgForEnd AND cfgForBeginning AND ALSO TO MAKE 1 TO SET THE LATTICES ABOVE THE ANALYSIS TODO begin and end func definition issue is mentioned inside of this 11 8 3 simplest form unstructured Simplest form No transfer action at call sites at all class UnstructuredPassInterDataflow virtual public InterProceduralDataflow public UnstructuredPassInterDataflow IntraProceduralDataflow intraDataflowAnalysis Inte rProcedural
31. n NodeState amp state visitor function public std ostream ostr analysisStatesToDOT Analysis 1 lda 1 3 75 Generic Dataflow Framework namespace Dbg VE veces void dotGraphGenerator Analysis a analysisStatesToDOT eas a IntraAnalysisResultsToDotFiles upia_eas eas upia_eas runAnalysis namespace Dbg 11 11 83 Example use Liao 12 6 2011 include rose h include lt list gt include lt sstream gt include lt iostream gt include lt fstream gt include lt string gt include lt map gt using namespace std TODO group them into one header include genericDataflowCommon h include VirtualCFGIterator h include cfgUtils h include CallGraphTraverse h include analysisCommon h include analysis h include dataflow h include latticeFull h include printAnalysisStates h include liveDeadVarAnalysis h int numFails 0 numPass 0 int main int argc char argv SgProject project frontend argc argv initAnalysis project generating index html for tracing the analysis Dbg init Live dead variable analysis Test index html liveDeadAnalysisDebugLevel 1 analysisDebugLevel 1 LiveDeadVarsAnalysis ldva project UnstructuredPassInterDataflow ciipd_ldva amp ldva ciipd_ldva runAnalysis Output the dot graph aooo Dbg dotGraphGenerator amp ldva return 0 76 TODO
32. 4 3 2 4 4 1 32bit macos 10 5 GCC 4 0 4 64bit macos 10 6 GCC 4 2 4 64bit x86__64 macos GCC 4 2 4 10 6 34bit debian GCC 3 4 6 4 0 4 4 1 2 GCC 3 4 6 4 0 4 4 1 2 4 2 4 4 3 2 4 4 1 4 2 4 4 3 2 4 4 1 13 4 Installation ROSE is released as an open source software package Users are expected to compile and install the software 4 1 Platform Requirement ROSE is portable to Linux and Mac OS X on IA 32 and x86 64 platforms In particular ROSE developers often use the following development environments e Red Hat Enterprise Linux 5 6 or its open source equivalent Centos 5 6 e Ubuntu 10 04 4 LTS Higher versions of Ubuntu are NOT supported due to the GCC versions supported by ROSE e Mac OS X 10 5 and 10 6 4 2 Software Requirement Here is a list for prerequisite software packages for installing ROSE e GCC 4 0 x to 4 4 x the range of supported GCC versions is checked by support rose m4 during configuration e gcc g e gfortran optional for Fortran support e boost library version 1 36 to 1 47 Again the range of supported Boost versions is checked by support rose m4 during configuration Sun Java JDK e GNU autoconf gt 2 6 and automake gt 1 9 5 GNU m4 gt 1 4 5 e libtool e bison byacc e flex e glibc devel e git e ZGRViewer a GraphViz DOT Viewer essential to view dot graphs of ROSE AST e install Graphviz first Graph Visualization Software Optional packages for additional features or
33. 4 Sample translators 0 0002 ee ee ee 20 5 How to build your translator 2 22 22 Coon 20 6 How to create a cross language translator 2 2 2 o 20 7 How to set up the makefile for a translator 20 8 How to debug a translator 22 m Con nn 20 9 How to add a new project directory 22 22 mn 20 10 How to fix a bug 2 2 Coon nn 20 11 How to add a ROSE commandline option Lessons Learned 21 1 Do Not Format Indent other people s code 21 2 Physical locations matter 2 2 2 Eon nn 21 3 Choose your development platform carefully 2 222 2 21 4 Use different git repositories for different tasks 2 222 220 21 5 Introducing software dependencies very carefully 21 6 Create Exacting Tests Early and Often 21 7 Keep Code Readable While Coding 0 21 8 Think Before You Code 020002 ee ee eee 21 9 Remember The User 20 0002 eee ee ee eee 127 127 128 128 129 129 129 130 131 132 133 133 137 141 144 147 148 149 151 151 157 158 161 161 161 163 166 171 176 177 Contents 22 23 24 25 26 27 28 21 10 The User is Paramount 2 a a 21 11 references 22 2 Se ey A A A BS O Testing 22 1 make check rules m nn nn 22 27 Benchmarks 2 2u A DM hese we aN 22 3 Modena Jt Test Suite 22 CC oo En En 22 8
34. 908 75280 93960 354636 e 123 12010 3717 199087 C C Header 915 28302 38412 121373 Bourne Shell 17 3346 4347 25326 Perl 4 743 1078 7888 Java 18 1999 4517 7096 m4 1 747 20 6489 Python 34 1984 1174 5363 make 148 1682 1071 3666 C 11 899 274 2546 SQL 1 o 0 1817 Pascal 5 650 31 1779 CMake 168 1748 4880 1702 yacc 3 352 186 1544 3 https mailman nersc gov mailman listinfo rose public 134 General Visual Basic 6 228 421 1180 Ruby 11 281 181 809 Teamcenter def 3 3 0 606 lex 2 103 47 331 css 1 95 32 314 Fortran 90 d 34 6 244 Tcl Tk 2 29 6 212 HTML 1 8 0 15 2383 130523 154360 19 1 4 How large is ROSE To show top level information only in MB du msl sort nr 170 tests 109 projects 90 src 19 docs 16 winspecific 16 ROSE_ResearchPapers 15 binaries 7 scripts 5 LicenseInformation 4 tutorial 4 autom4te cache 2 libltdl 2 exampleTranslators 2 configure 2 config 2 ChangeLog Sort directories by their sizes in MegaBytes du m sort nr gt size txt 709 A 250 git 245 git objects 243 git objects pack 170 tests 109 projects 90 src 76 tests CompileTests 50 tests RunTests 40 tests RunTests FortranTests 135 Frequently Asked Questions FAQ 34 29 27 23 23 22 21 19 18 18 18 16 16 15 15 15 14 tests RunTests FortranTests LANL_POP tests RunTests FortranTests LANL_POP netcdf 4 1 1 src 3rdPartyLibra
35. AST The translation process may add delete or modify the information stored in AST 20 3 1 Overview A ROSE based translator usually has the following steps 1 Search for the AST nodes you want to translate 2 Perform the translation action on the found AST nodes This action can be one of two major variants e Updating the existing AST nodes e Creating new AST nodes to replace the original ones This is usually cleaner approach than patching up existing AST and is better supported by SageBuilder and Sagelnterface functions e Deep copying existing AST subtrees to duplicate the code May expression subtrees should not be shared So deep copy them is required to get the correct AST e Optionally update other related information for the translation 20 3 2 First Step Get familiar with the ASTs before and after your translation So you know for sure what your code will deal with and what AST you code will generate The best way is to prepare simplest sample codes and carefully examine the whole dot graphs of them 20 3 3 Design considerations It is usually a good idea to e separate the searching step from the translation step so one search traversal can be reused by all sorts of translations e When design the order of searching and translation be careful about if the translation will negatively impact on the searching e Please void pre order traversal since you may end up modifying AST nodes to be visited later on similar
36. CENSE The Free Software Foundation may publish new re vised versions of the GNU Free Documentation Li cense from time to time Such new versions will be similar in spirit to the present version but may dif fer in detail to address new problems or concerns See http www gnu org copyleft Each version of the License is given a distinguish ing version number If the Document specifies that a particular numbered version of this License or any later version applies to it you have the op tion of following the terms and conditions either of that specified version or of any later version that has been published not as a draft by the Free Soft ware Foundation If the Document does not specify a version number of this License you may choose any version ever published not as a draft by the Free Software Foundation If the Document speci fies that a proxy can decide which future versions of 4 Combined Works You may convey a Combined Work under terms of your choice that taken together effectively do not restrict modification of the portions of the Library contained in the Combined Work and reverse en gineering for debugging such modifications if you also do each of the following a Give prominent notice with each copy of the Combined Work that the Library is used in it and that the Library and its use are covered by this Li cense b Accompany the Combined Work with a copy of the GNU GPL and this license document
37. Chapter 17 on page 115 3 Chapter 18 on page 127 88 Proposing Workflow Changes e Project Specific Tasks e Private Issue Tracking e Private Documentation e Using redmine s wiki e Github e Internal http github 11n1 gov for code review only e External https github com rose compiler rose public hosting code pubic issue tracking for general ROSE bugs and features e Rosebot to automate Github workflow preliminary testing policies git hooks automatically add reviewers etc 15 3 4 Testing e Jenkins http hudson rose 30 8080 continuous integration of new features bugfixes 15 3 5 Documentation e See more at ROSE Compiler Framework Documentation 15 3 6 Publicity e Website http www rosecompiler org content management system hooked up with all other components 15 4 Proposing Workflow Changes Major workflow improvements and changes should be thoroughly tested and reviewed by staff members before deployment since they may have profound impact on the project How to propose a workflow change e Submit a ticket on github com s rose public rose issue tracker In the ticket provide the following information e What is it Explain what change is proposed e Why the changes the long term benefits for our productivity and quality of work e The cost of the changes learning curve maintainability purchase cost 4 Chapter 2 on page 7 89 Workflow 15 5 Reviewing Workflow Change Propos
38. Def use analysis 22 Co oo on nn 10 4 Pointer Analysis 2 2 e Con 105 SSA re are ae A be oe tes epee RE 10 6 Side Effect Analysis 0000020 00 10 7 Generic Dataflow Framework 2 2 22 2 2 22m nn nn 10 8 Dependence analysis 2 2 2 2 CE nn nen Generic Dataflow Framework 11 1 Introd ctient asa ey aed eke ee rien 11 2 Implemented analysis 2 2 2 2 2 CL EEE nn 11 3 Function nodeState and FunctionState 11 4 lattices Ds na are an Ate oe dw eles 11 5 Transfer Function 0000202 eae 11 6 Control flow graph and call graph 2 222 20 11 7 Analysis Driver gesis eee eee eee ae 11 8 Inter procedural analysis 2 2 onen 11 9 How to use one analysis 22 2 CL om En 11 10 Westin sy 2 are ers ne Yee 11 17 How t debug si amp 2 o Cay aed Bea a een 11 12 TODOS 335 Sy 2er er rn rn A Program Optimizations 29 29 29 30 30 31 31 32 32 32 33 35 35 35 35 35 36 36 37 39 39 43 43 44 45 46 46 46 49 49 49 50 53 55 58 59 69 71 73 74 77 79 Contents ROSE Projects 81 IS minitermite A Mar Be sees Pa one ss We eee ly ee ee 82 Developer s Guide 83 14 1 Basic skills for ROSE developers 2 2 o nn 83 14 2 Valued Contributions 2 2 2 2 2 83 14 3 Milestones fora ROSE developers o e o 84 14 4 Termination checklist a a aa 85 145 dereview Ser war an ee ee ee ke a ath eel a eee 85 14 6 Worki
39. Here are some general guidelines for creating a new virtual machine Following these exact steps are not required although they are recommended to ensure a consistent user experience with the ROSE VM s Please make sure you document the whole process in its entirety These steps must be performed within the VM guest OS 1 Install the prerequisite software using the platform s software package manager Only as a last resort should you manually install software Use the platform s default software versions if possible Use bash as the default login shell 1 Chapter 4 on page 15 23 Virtual machine image 2 Setup the ROSE workspace export ROSE_HOME HOME development projects rose export ROSE_SOURCE HOME development projects rose src export ROSE_INSTALL HOME development opt rose mkdir p ROSE_HOME mkdir p ROSE_INSTALL 3 Clone the ROSE repository as src cd ROSE_HOME git clone https github com rose compiler rose ROSE_SOURCE 4 Configure build and install ROSE cd ROSE_SOURCE Run ROSE s Autotools bootstrap script ROSE_SOURCE build Configure ROSE using the minimal useful configuration ROSE_SOURCE configure prefix ROSE_INSTALL with boost lt local opt gt make make install 5 Verify ROSE installation works 6 Create simple demo translator s in ROSE_ HOME demo 24 6 ROSE tools ROSE is a compiler framework to build customized c
40. LLNL 5 1 2 Content of the VM Image Copy amp paste from README within the virtual machine This is a virtual machine image for the ROSE source to source compiler framework sourcetree cloned from github com rose compiler rose on July 21 2012 e home demo rose buildtree e home demo buildrose installation tree prefix path e home demo opt rose inst A script to set environment variables to use the installed ROSE tools e home demo set rose env 21 Virtual machine image A test translator e home demo myTranslator Some dot graphs of a simplest function Type run sh file dot will view a dot file e home demo dotGraphs 5 1 3 Install VMware Player You have to install VMware Player to your machine to use the virtual machine image Goto http www vmware com go downloadplayer Select the right bundle for your platform For example VMware Player 4 0 4 744019 i386 txt After downloading assuming you are using Ubuntu 10 04 e chmod a x VMware Player 4 0 4 744019 1386 txt e sudo VMware Player 4 0 4 744019 i386 txt e follow the GUI to finish the installation To start VMPlayer goto Menu gt Applications gt System Tools gt VMware Player 5 1 4 Open Play the virtual machine After downloading and untar the tar gz package to a directory use VMware player to open the configuration file of the directory 5 2 How was the virtual machine made 5 2 1 Host Machine We used Ubuntu 10 04 LTS as a host machine to c
41. So we can have clear guideline for code review for what is mandatory and what is optional e rename three places of the pasted text with the desired page name for example ROSE Compiler Framework How to do XYZ How to do XYZ dhunparserurl ROSE Compiler Framework How to do XYZ e click save page e You will see red text trying to link to the not yet existing How to do XYZ page e click any of the red text it will bring you to an editing window to add content of your new how to page e you can now add new content and save it e Again each how to wiki page should NOT contain any level one or level two heading so it can be included at the correct levels in the print version of this wikibook 20 1 10 Insert image to wiki page e To use your own image in wiki page you have to upload the image to http commons wikimedia org e Once you upload the image it will become public to all wikibooks users Be sure to declare your copyright if the image is created by yourself e Following this instruction to insert image and adjust the layout of your page http en wikibooks org wiki Using_Wikibooks Inserting_Images 20 1 11 Rules of the content e Only level three headings and higher are allowed in a how to page This is necessary for the how to page to be correctly included into the final one page print version of this wikibook Sorry about this restriction 156 How to incrementally work on a project e Again pleas
42. ability to install modified object code on the User Product for ex ample the work has been installed in ROM The requirement to provide Installation Informa tion does not include a requirement to continue to provide support service warranty or updates for a work that has been modified or installed by the re cipient or for the User Product in which it has been modified or installed Access to a network may be denied when the modification itself materially and adversely affects the operation of the network or violates the rules and protocols for communication across the network Corresponding Source conveyed and Installation Information provided in accord with this section must be in a format that is publicly documented and with an implementation available to the public in source code form and must require no special password or key for unpacking reading or copying 7 Additional Terms Additional permissions are terms that supplement the terms of this License by making exceptions from one or more of its conditions Additional permis sions that are applicable to the entire Program shall be treated as though they were included in this License to the extent that they are valid un der applicable law If additional permissions apply only to part of the Program that part may be used separately under those permissions but the entire Program remains governed by this License without regard to the additional permissions
43. advanced users 1 http www centos org 2 https github com rose compiler rose blob master config support rose m4 3 https github com rose compiler rose blob master config support rose m4 15 Installation e libxml2 devel e sqlite e texlive full need for building LaTeX docs 4 2 1 Installing boost The installation of Boost may need some special attention Download a supported boost version from http sourceforge net projects boost files boost For version 1 36 to 1 38 configure prefix home usera opt boost 1 35 0 make make install Ignore the warning like Unicode ICU support for Boost Regex not found For version 1 39 and 1 47 create the boost installation directory first In boost source tree e bootstrap sh prefix your_boost_install_path e bjam j4 install prefix your_boost_install_path libdir your_boost_install_ path lib Remember to export LD_LIBRARY_PATH for the installed boost library for example LD_LIBRARY_PATH LD_LIBRARY_PATH home leo opt boost_1 45 0_inst lib export PATH LD_LIBRARY_PATH 4 2 2 Installing Java JDK Download Java SE JDK from http www oracle com technetwork java javase downloads index html For example you can download jdk 7u5 linux i586 tar gz for your Linux 32 bit system After untar it to your installation path remember to set environment variables for Java JDK jdk path should be search first before other paths PATH home le
44. and 2 were thus incorporated prior to November 1 2008 The operator of an MMC Site may republish an MMC contained in the site under CC BY SA on the same site at any time before August 1 2009 pro vided the MMC is eligible for relicensing ADDEN DUM How to use this License for your documents To use this License in a document you have written include a copy of the License in the document and put the following copyright and license notices just after the title page Copyright C YEAR YOUR NAME Permission is granted to copy distribute and or modify this doc ument under the terms of the GNU Free Documen tation License Version 1 3 or any later version pub lished by the Free Software Foundation with no Invariant Sections no Front Cover Texts and no Back Cover Texts A copy of the license is included in the section entitled GNU Free Documentation License If you have Invariant Sections Front Cover Texts and Back Cover Texts replace the with Texts line with this with the Invariant Sections being LIST THEIR TI TLES with the Front Cover Texts being LIST and with the Back Cover Texts being LIST If you have Invariant Sections without Cover Texts or some other combination of the three merge those two alternatives to suit the situation If your document contains nontrivial examples of program code we recommend releasing these exam ples in parallel under your choice of free software license such as the GNU Gene
45. and email will make it easier for us to evaluate the contributions that you ve made to our project Guidelines e Name You MUST use your official name you commonly use for work business not nickname or alias which cannot be easily recognized by co workers managers or sponsors e Email You MUST use your email commonly used for work It can be either your company email or your personal email gmail if you DO commonly use that personal email for business purpose To check if your author and email are configured correctly git config user name lt your name gt git config user email lt your email gt Alternatively you can just type the following to list all your current git configuration variables and values including name and email information git config 1 To set your name and email git config global user name lt Your Name gt git config global user email lt your email com gt 16 2 2 Commit messages It is important to have concise and accurate commit messages to help code reviewers do their work Example commit message excerpt from link Binary Analysis SMT solver statistics documentation Replaced the SMT class wide number of calls statistic with a more flexible and extensible design that also tracks the amount of I O between ROSE and the SMT solver The new method tracks statistics on a per solver basis as well as a class wide basis and allows the statistics to be reset at artibrary p
46. assert or imply en dorsement of any Modified Version 5 COMBIN ING DOCUMENTS You may combine the Document with other docu ments released under this License under the terms defined in section 4 above for modified versions provided that you include in the combination all of the Invariant Sections of all of the original doc uments unmodified and list them all as Invariant Sections of your combined work in its license no tice and that you preserve all their Warranty Dis claimers The combined work need only contain one copy of this License and multiple identical Invariant Sec tions may be replaced with a single copy If there are multiple Invariant Sections with the same name but different contents make the title of each such section unique by adding at the end of it in paren theses the name of the original author or publisher of that section if known or else a unique number Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work In the combination you must combine any sections Entitled History in the various original docu ments forming one section Entitled History like wise combine any sections Entitled Acknowledge ments and any sections Entitled Dedications You must delete all sections Entitled Endorse ments 6 COLLECTIONS OF DOCUMENTS You may make a collection consisting of the Docu ment and other documents released under this
47. be included at the correct levels in the print version of this wikibook 20 1 8 Insert image to wiki page e To use your own image in wiki page you have to upload the image to http commons wikimedia org e Once you upload the image it will become public to all wikibooks users Be sure to declare your copyright if the image is created by yourself e Following this instruction to insert image and adjust the layout of your page http en wikibooks org wiki Using_Wikibooks Inserting Images 155 How tos 20 1 9 Rules of the content e Only level three headings and higher are allowed in a how to page This is necessary for the how to page to be correctly included into the final one page print version of this wikibook Sorry about this restriction e Again please don t use level one or level two headings in a how to page e Keep each how to short and focused Readers are expected to only spend 30 minutes or much less to quickly learn how to do something using ROSE e After you created a new how to page and saved your contributions Please go to the print version to make sure it shows up correctly e Here is the link http en wikibooks org wiki ROSE_Compiler_Framework Print_version e Having new content show up in the print version will make sure it is really visible and consistent with the rest of the book please specify the how to topic is the current practice or the proposed new ways of doing things
48. code identityTranslator c helloWorld c It should generate an output file named rose_helloWorld c which should just look like your input code 18 Trouble shooting 4 10 Trouble shooting We list common issues associated with ROSE s installation 4 10 1 EDG binary If you do not have the EDG frontend source code ROSE s build system will automatically attempt to download an appropriate EDG binary using wget during the build process i e make C src frontend CxxFrontend The EDG binaries are platform specific and have historically been a cause of issues i e Autoconf detecting wrong host build platform types One possible remedy to these problems is to use the Autoconf Build and Host Options 1 Check what build system Autoconf thinks you have config config guess x86_64 unknown linux gnu 2 Use the appropriate Autoconf options during configuration of ROSE ROSE configure build host target See Using the Target Type A real user s solution Hi Justin Checking the config guess file in source tree I search the apple darwin for detail information in build option then I found that UNAME PROCESSOR and UNAME_RELEASE are needed in build First I type uname m for finding UNAME_PROCESSOR in config guess result x86_64 Second I type uname r for finding UNAME_RELEASE result 10 8 0 darwin kernel version Third I type command to configure again but I added b
49. difficult and open research and development questions They may have no clue either e They just feel lazy sometimes or are taking a thing called vacation Possible alternatives to have your questions answered and your problems solved in a timely fashion 1 https mailman nersc gov pipermail rose public 2 https mailman nersc gov mailman listinfo rose public 133 Frequently Asked Questions FAQ e Please do you own homework first e g Google e The ROSE team is actively addressing the documentation problem through an internal code review process to enforce well documented contributions going forward e Help others to help yourself Answer questions on the rose public nersc gov mailing list and contribute to this community editable Wikibook e Find ways to formally collaborate with or fund the ROSE team Things go faster when money is flowing Sad but true reality in this busy world 19 1 3 How many lines of source code does ROSE have Excluding the EDG submodule and all source code comments the core of ROSE rose src has about 674 000 lines of C C source code as of July 11 2012 Including tests projects and tutorial directories ROSE has about 2 Million lines of code Some details are shown below rose src cloc 1 56 p1 3076 text files 2871 unique files 716 files ignored http cloc sourceforge net v 1 56 T 26 0 s 91 7 files s 39573 3 lines s Language files blank comment code C
50. directory into ROSE https github com rose compiler rose commit edf68927596960d96bb7 7 3ef a25af5e090168f4a Please look through the diffs so you know what files to be added and changed for a new project Essentially a basic project should contain 173 How tos e a README file explaining what this project is about algorithm design implementation etc e a translator acts as a driver of your project e additional source files and headers as needed to contain the meat of your project e test input files e Makefile am to e compile and build your translator e contain make check rule so your translator will be invoked to process your input files and generate expected results To connect your project into ROSE s build system you also need to e Add one more subdir entry into projects Makefile am for your project directory e Add one line into config support rose m4 for EACH new Makefile generated from each Makefile am used by your projects 20 9 5 Installing project targets Install your project s content to a separate directory within the user s specified prefix location The reason behind this is that we don t want to pollute the core ROSE installation space By doing so we can reduce the complexity and confusion of the ROSE installation tree while eliminating cross project file collisions It also keeps the installation tree modular Example This example uses a prefix for installation It also maintains Semantic Versio
51. docs Rose powerpoints rose_compiler_users pptx 2428 src 3rdPartyLibraries ckpt wrapckpt c 2408 projects DatalogAnalysis jars weka jar 2220 scripts graph tar 1900 src 3rdPartyLibraries antlr jars antlr 3 3 complete jar 1884 src 3rdPartyLibraries antlr jars antlr 3 2 jar 1848 src midend programTransformation ompLowering run_me_defs inc 1772 src 3rdPartyLibraries qrose docs QROSE pdf 1732 tests CompileTests Cxx_tests longFile C 1724 src midend programTransformation ompLowering run_me_task_defs inc 1656 ChangeLog 1548 tests roseTests binaryTests yicesSemanticsExe ans 1548 tests roseTests binaryTests yicesSemanticsLib ans 1480 ROSE_ResearchPapers 1997 ExpressionTemplatePerformancelssues IPPS pdf 1408 docs Rose powerpoints ExaCT_AllHands_March2012_ROSE pptx 19 2 Compilation 19 2 1 Cannot download the EDG binary tar ball Three possible reasons e the website hosting EDG binaries is down there is a manual way to get the binary e we don t support the platform you use so there is no EDG binary is available for you e you cloned your rose from an un official repo so the build process cannot figure out the right version of EDG binary for you there is a solution mentioned below It is possible that the rosecompiler org website is down for maintenance 137 Frequently Asked Questions FAQ So you may encounter the following error message make 3 Entering directory home leo workspace git
52. dotGeneratorWholeASTGraph whole AST graph showing more details It provides filter options to show hide certain AST information command line 26 AST dot graph generators dotGeneratorWholeASTGraph yourcode c dotGeneratorWholeASTGraph help rose help rose dotgraph asmFileFormatFilter enable asmFileFormat filter rose dotgraph asmTypeFilter enable asmType filter rose dotgraph binaryExecutableFormatFilter enable binaryExecutableFormat filter rose dotgraph commentAndDirectiveFilter enable commentAndDirective filter rose dotgraph ctorInitializerListFilter enable ctorInitializerList filter rose dotgraph defaultFilter enable default filter rose dotgraph defaultColorFilter enable defaultColor filter rose dotgraph edgeFilter enable edge filter rose dotgraph expressionFilter enable expression filter rose dotgraph fileInfoFilter enable fileInfo filter rose dotgraph frontendCompatibilityFilter enable frontendCompatibility filter rose dotgraph symbolFilter enable symbol filter rose dotgraph emptySymbolTableFilter enable emptySymbolTable filter rose dotgraph typeFilter enable type filter rose dotgraph variableDeclarationFilter enable variableDeclaration filter rose dotgraph variableDefinitionFilter enable variableDefinitionFilter filter rose dotgraph noFilter enable no filtering Current filter flags values are m_asmFileFormat 0 m_asmType 0 m_binaryExecutableFormat 0 m_commentAndDirective
53. e Use cpp or cxx for C source files What to avoid capitalized C for source files This will cause some issue when porting ROSE to case insensitive file systems References e http www parashift com c faq src file ext html 16 9 README All major directories within ROSE git repository should have a README file e projects projectXYZ MUST have a README file File name should be README what to avoid e README txt e readme 16 9 1 Required Content For all major directories in ROSE there should be a README explaining e What is in this directory e What does this directory accomplish 11 http www parashift com c faq using namespace std html 12 http www possibility com Cpp CppCodingStandard html dgdu 105 Coding Standard e Who added it and when Each project directory must have a README to explain e What this project is about e Name of the project e Motivation Why do we have this project e Goal What do we want to achieve e Design Implementation So next person can quickly catch up and contribute to this project e How do we design implement it e What is the major algorithm e Brief instructions about how to use the project e Installation e Testing e Or point out where to find the complete documentation e Status e What works e What doesn t work e Known limitations e References and citations for the underlying algorithms e Authors and Dates 16 9 2 Format Format of README e text format
54. few languages 19 2 4 Can ROSE accept incomplete code https mailman nersc gov pipermail rose public 2011 July 001015 html ROSE does not handle incomplete code Though this might be possible in the future It would be language dependent and likely depend heavily on some of the language specific tools that we use internally This is however not really a priority for our work If you want to for example demonstrate how some of the internal tools we are using or alternative tools that we could use might handle incomplete code this might be interesting and we could discuss it For example we are not presently using Clang but if it handled incomplete code that might be interesting for the future I recall that some of the latest EDG work might handle some incomplete code and if that is true then that might be interesting as well I have not attempted to handle incomplete code with OFP so I am not sure how well that could be expected to work Similarly I don t know what the incomplete code handling capabilities of ECJ Java support is either If you know any of these questions we could discuss this further I have some doubts about how much meaningful information can come from incomplete code analysis and so that would worry me a bit I expect it is very language dependent and there would be likely some constraints on the incomplete code So understanding the subject better would be an additional requirement for me 19 2 5 Can ROSE analyze L
55. for his insightful comments for some of the initial design document requirements 16 3 2 Guideline e All new ROSE analyses transformations and optimizations must have an accompanying design document to be peer reviewed before the actual implementation begins e Be specific enough that someone with ROSE skills who is not the original designer could in principle implement the design just by looking at the document e It s to be expected that different developers will make different low level choices about data structures etc 16 3 3 Requirement vs Design Document If the requirements document is the why of the software then the technical design document is the how to For simplicity we put both requirements and design into a single document for now We allow a separated requirement analysis document if necessary 6 http www ehow com how_6734245_write software design document htm1 ixzz22E1xFTCS 7 http www cs rice edu vs3 home Vivek_Sarkar html 8 http www rice edu 94 Design Document The purpose of writing the technical design document is to guide developers in implementing and fulfilling the requirements of the software it s the software s blueprint 16 3 4 Format Documents must be e Written in LaTex for re usability in publications and proposals e Stored under version control to support collaborative writing Your document should at a minimum include these formal sections e Title page
56. format ters or for automatic translation to a variety of for mats suitable for input to text formatters A copy made in an otherwise Transparent file format whose markup or absence of markup has been arranged to thwart or discourage subsequent modification by readers is not Transparent An image format is not Transparent if used for any substantial amount of text A copy that is not Transparent is called Opaque Examples of suitable formats for Transparent copies include plain ASCII without markup Tex info input format LaTeX input format SGML or XML using a publicly available DTD and standard conforming simple HTML PostScript or PDF de signed for human modification Examples of trans parent image formats include PNG XCF and JPG Opaque formats include proprietary formats that can be read and edited only by proprietary word processors SGML or XML for which the DTD and or processing tools are not generally available and the machine generated HTML PostScript or Notwithstanding any other provision of this Li cense you have permission to link or combine any covered work with a work licensed under version 3 of the GNU Affero General Public License into a single combined work and to convey the result ing work The terms of this License will continue to apply to the part which is the covered work but the special requirements of the GNU Affero General Public License section 13 concerning interaction through a network w
57. gt amp curNodeState DataflowNode curDFNode int nodelndex const std vector lt Lattice gt amp nextNodeState DataflowNode nextDFNode 11 7 7 live dead variable Backward Intra Procedural Dataflow Analysis e g liveness analysis use gt backward gt defined e class IntraBWDataflow public IntraUniDirectionalDataflow class LiveDeadVarsAnalysis public IntraBWDataflow protected funcSideEffectUses fseu public LiveDeadVarsAnalysis SgProject project funcSideEffectUses fseu NULL Generates the initial lattice state for the given dataflow node in the given function with the given NodeState 68 Inter procedural analysis void genInitState const Function amp func const DataflowNode amp n const NodeState amp state std vector lt Lattice gt amp initLattices std vector lt NodeFact gt amp initFacts boost shared_ptr lt IntraDFTransferVisitor gt getTransferVisitor const Function amp func const DataflowNode amp n NodeState amp state const std vector lt Lattice gt amp dfInfo return boost shared_ptr lt IntraDFTransferVisitor gt new LiveDeadVarsTransfer func n state dfInfo fseu bool transfer const Function amp func const DataflowNode amp n NodeState amp state const std vector lt Lattice gt amp dfInfo assert 0 return false 5 11 8 Inter procedural analysis Key transfer function that is applied to call sites to perform the approp
58. https github com rose compiler rose blob master src midend programTransformation ompLowering e The OpenMP runtime interface is defined in libxomp h and xomp c under the same ompLowering directory mentioned above Experimental OpenMP Acclerator Model Implementation e OpenMP Acclerator Model Implementation 7 2 UPC UPC 1 1 1 this is based on the EDG 3 3 frontend http www edg com index php location c_frontend http fortran parser sourceforge net http rosecompiler org ROSE_UserManual ROSE UserManual pdf http rosecompiler org ROSE_ResearchPapers 2010 06 AROSEBasedOpenMP3 OResearchCompiler IWOMP pdf http en wikibooks org wiki ROSEY20Compiler 20Framework 2FOpenMP 20Acclerator 20Model 20Implementation gt WNP al 29 Supported Programming Languages e The supported version is limited by the EDG 3 3 frontend which only supports UPC 1 1 1 UPC VERSION string is defined as 200310L ROSE uses EDG 3 3 currently and it originally only supported UPC 1 0 We merged the UPC 1 1 1 support from EDG 3 10 into our EDG 3 3 frontend We have also added the required work to support UPC 1 2 Documentation e Chapter 13 UPC Support of the ROSE manual http rosecompiler org ROSE_ UserManual ROSE UserManual pdf Tests make check rule under e rose tests CompileTests UPC_ tests An example UPC to C translator roseupcc e Not full featured Only intended to serve as a start point for anybody who is interested
59. idx 1 at ROSE src frontend SageIII virtualCFG memberFunctions C 1471 6 0x00002aaaad647e69 in VirtualCFG CFGNode outEdges this 0x7fffffffb530 at ROSE src frontend SagelII virtualCFG virtualCFG C 636 7 0x000000000040bf7f in getReachableNodes n s at ROSE tests CompileTests virtualCFG_tests testVirtualCFG C 13 5 Next we ll move backwards or upwards in the program to get to the point of assertion gdb up 1 0x0000003752231d30 in abort from 1ib64 libc so 6 gdb up 2 0x0000003752229706 in __assert_fail from 1ib64 libc so 6 gdb up 3 0x00002aaaad6437b2 in VirtualCFG CFGEdge CFGEdge this 0x7fffffffb300 src tgt at 1ROSEJ src frontend SagellI virtualCFG virtualCFG h 111 111 CFGEdge CFGNode src CFGNode tgt src src tgt tgt assert src getNode NULL amp amp tgt getNode NULL Okay so the assertion is inside of a constructor for CFGEdge CFGEdge CFGNode src CFGNode tgt src src tgt tgt assert src getNode NULL amp amp tgt getNode NULL This 169 How tos is the failed assertion Unfortunately we can t tell at a glance which of the two conditions in the assertion is failing 6 Figure out why the assertion is failing Let s examine the two conditions in the assertion gdb p src getNode 1 SgNode Oxbfaf10 So src getNode is returning a non null pointer to an SgNode How bout tgt getNode g
60. lattice of bit vectors of length n Constructing complex lattices from multiple less complex lattices e Example The product operation which combines concatenates lattices elementwise e The product of two lattices L1 and L2 with meet operators M1 M2 respectively L1 x L2 e The elements in the lattice lt x1 x2 gt x1 from L1 x2 from L2 e The meet operator lt x1 x2 gt M lt yl y2 gt lt xl M yl x2 M y2 gt The join operation lt xl x2 gt J lt yl y2 gt lt xl J yl x2 J y2 gt e Example e BV n is the product of n copies of the trivial bit vector attice BV 1 with bottom 0 and top 1 193 Lattices Graphical Representation BV 3 111 110 101 O11 x x 100 010 001 000 Here meet and join operators induce a partial order on the lattice elements x is less than or equal to lt y if an only ifx My x For the BV 3 000 lt 010 lt 101 lt 111 The partial order on the lattice is e Transitive x lt y and y lt z then x lt z e Antisymmetric if x lt y and y lt x then x y e Reflexive for all x x lt x The height of the lattice is the length of its longest strictly ascending chain e The maximal n such that there exists a strictly ascending chain x1 x2 xn such that e Bottom xl lt x2 lt xn Top For BV 3 lattice height 4 24 6 Monotonic Functions A monotonic function is a function that preserves an ordering 24 7 Examples A function f from L
61. lattices for each CFG node etc virtual IntraProceduralAnalysis No re entry analysis will be executed once data flow intra procedural analysis now lattices are interested class IntraProceduralDataflow virtual public IntraProceduralAnalysis analysis dataflow h initialize lattice etc for a given dataflow node within a function virtual void genInitState const Function amp func const DataflowNode amp n const NodeState amp state std vector lt Lattice gt amp initLattices std vector lt NodeFact gt amp initFacts virtual bool runAnalysis const Function amp func NodeState state bool analyzeDueToCallers std set lt Function gt calleesUpdated 0 the analysis on a function could be triggered by the state changes of function s callers or callees std set lt Function gt visited make sure a function is initialized once when visited multiple times class IntraUnitDataflow virtual public IntraProceduralDataflow transfer function operate on lattices associated with a dataflow node considering its current state virtual bool transfer const Function amp func const DataflowNode amp n NodeState amp state const std vector lt Lattice gt amp dfInfo 0 3 Uni directional dataflow either forward or backward but not both directions class IntraUniDirectionalDataflow public IntraUnitDataflow public bool runAnalysis const Function amp func NodeState state bool
62. n zZ a fay2 t yYy z 2 pot e no n_ 2n erfe x lt fy e dt N roll n x A 209 30 Edits 91 74 1196 16 39 Contributors User Chunhualiao Doubleotoo GoblinInventor Invapid Liao Matzke Peihunglin QUBot QuiteUnusual ComOnNroaw kwnr http en wikibooks org w index php title User http en wikibooks org w index php title User http en wikibooks org w index php title User http en wikibooks org w index php title User http en wikibooks org w index php title User http en wikibooks org w index php title User http en wikibooks org w index php title User http en wikibooks org w index php title User http en wikibooks org w index php title User Chunhualiao Doubleotoo GoblinInventor Invapid Liao Matzke Peihunglin QUBot QuiteUnusual 211 List of Figures e GFDL Gnu Free Documentation License http www gnu org licenses fdl html e cc by sa 3 0 Creative Commons Attribution ShareAlike 3 0 License http creativecommons org licenses by sa 3 0 e cc by sa 2 5 Creative Commons Attribution ShareAlike 2 5 License http creativecommons org licenses by sa 2 5 e cc by sa 2 0 Creative Commons Attribution ShareAlike 2 0 License http creativecommons org licenses by sa 2 0 e cc by sa 1 0 Creative Commons Attribution ShareAlike 1 0 License http creativecommons org licenses by sa 1 0 e cc by 2 0 Creative Commons Attribution
63. node only the nodes which represent code of the same file as the start node node traverse full AST nodes which represent code from 19 3 3 Should SgIfStmt get_true_body return SgBasicBlock https mailman nersc gov pipermail rose public 2011 April 000930 html Both true false bodies were SgBasicBlock before Later we decided to have more faithful representation of both blocked with and single statement without bodies So they are SgStatement SgBasicBlock is a subclass of SgStatement now But it seems like the document has not been updated to be consistent with the change You have to check if the body is a block or a single statement in your code Or you can use the following function to ensure all bodies must be SgBasicBlock A wrapper of all ensureBasicBlockAs above to ensure the parent of s is a scope statement with list of statements as children otherwise generate a SgBasicBlock in between SgLocatedNode Sagelnterface ensureBasicBlockAsParent SgStatement s 19 3 4 How to handle include header h if define etc It is called preprocessing info within ROSE s AST They are attached before after or within a nearby AST node only the one with source location information An example translator is provided to traverse the input code s AST and dump information about the found preprocessing information exampleTranslators defaultTranslator preprocessingInfoDumper c main cxx Fo
64. of the comments may be just suggestions Use your own judgement The bottomline is the balance between quality and productivity Please do not close the pull request You can push your new commits to the same branch again and comment on the pull request to indicate there are new updates Please review them again So the reviewer would not need to go to another pull request to see what were the previous comments before 17 5 Reviewer Checklist What to look out for as a code reviewer 7 120 https github com rose compiler rose issues 79 Reviewer Checklist Be familiar with the current Coding Standard as a general guideline to perform the code review Allocate up to 1 hour at a time to review approximately 500 1000 lines of code a longer time may not pay off due to the attention span limits of human brains 17 5 1 What to check Six major things to check Documentation What are the commits about Is this reflected in README source comments or LaTex files Style Does the coding style follow our standard Is the code clean robust and maintainable Interface Does the code has a clean and simple interface to be used by users Algorithm Does the code have sufficient comments about what algorithm is used Is the algorithm correct and efficient space and time complexity Implementation Does the code correctly implement the documented algorithm s Testing Does the code have the accompanying test translator and
65. page e optional step create an account and log in e Goto http en wikibooks org wiki ROSE_Compiler_Framework How tos e Click on Edit tab on the right top of the How tos page e Copy and paste one existing How to to the end of the page for example ROSE Compiler Framework How to write a How to How to write a How to dhunparserurl ROSE Compiler Framework How to write a How to Quick short and focused tutorials about how to do common tasks as a ROSE developer Please create a new wikibook page for each how to topic Each how to wiki page should NOT contain any level one or level two heading so it can be included at the correct levels in the print version of this wikibook Create a new page optional step create an account and log in Goto http en wikibooks org wiki ROSE_Compiler_Framework How tos Click on Edit tab on the right top of the How tos page Copy and paste one existing How to to the end of the page for example lt pre gt ROSE Compiler Framework How to write a How to How to write a How to dhunparserurl ROSE Compiler Framework How to write a How to Quick short and focused tutorials about how to do common tasks as a ROSE developer 151 How tos Please create a new wikibook page for each how to topic Each how to wiki page should NOT contain any level one or level two heading so it can be included at the correct levels in the print version of this wi
66. printed covers that bracket the whole aggregate 8 TRANSLATION 31 3 GNU Lesser General Public License GNU LESSER GENERAL PUBLIC LICENSE Version 3 29 June 2007 Copyright O 2007 Free Software Foundation Inc lt http fsf org gt Everyone is permitted to copy and distribute verba tim copies of this license document but changing it is not allowed This version of the GNU Lesser General Public Li cense incorporates the terms and conditions of ver sion 3 of the GNU General Public License supple mented by the additional permissions listed below 0 Additional Definitions As used herein this License refers to version 3 of the GNU Lesser General Public License and the GNU GPL refers to version 3 of the GNU General Public License The Library refers to a covered work governed by this License other than an Application or a Com bined Work as defined below An Application is any work that makes use of an interface provided by the Library but which is not otherwise based on the Library Defining a subclass of a class defined by the Library is deemed a mode of using an interface provided by the Library A Combined Work is a work produced by com bining or linking an Application with the Library The particular version of the Library with which the Combined Work was made is also called the Linked Version The Minimal Corresponding Source for a Com bined Work means the Correspond
67. programAnalysis genericDataflow state nodeState h It also provide static functions to e initialize NodeState for all DataflowNode e to retrieve NodeState for a given DataflowNode 50 Function nodeState and FunctionState class NodeState internal types map between analysis and set of lattices typedef std map lt Analysis std vector lt Lattice gt gt LatticeMap typedef std map lt Analysis std vector lt NodeFact gt gt NodeFactMap typedef std map lt Analysis bool gt BoolMap the dataflow information Above the node for each analysis that may be interested in the current node LatticeMap dfInfoAbove IN set in a dataflow the Analysis information Below the node for each analysis that may be interested in the current node LatticeMap dfInfoBelow OUT set in a dataflow the facts that are true at this node for each analysis that may be interested in the current node NodeFactMap facts Contains all the Analyses that have initialized their state at this node It is a map because TBB doesn t provide a concurrent set BoolMap initializedAnalyses static interfaces returns the NodeState object associated with the given dataflow node index is used when multiple NodeState objects are associated with a given node ex SgFunctionCallExp has 3 NodeStates entry function body exit static NodeState getNodeState const DataflowNode amp n int i
68. repo s master Notify system admin tool for the problem or manually fix it using the troubleshooting section of this page e notify a reviewer that you have a pull request requesting to merge your bugfix rc into your master branch You can assign the pull request to the reviewer so an email notification will be automatically sent to the reviewer Or you can add discussion within the pull request using revieweraccount NOTE please only click Comment on this issue once and manually refresh the web page Github Enterprise has a bug so it cannot automatically shown the newly added comment bug79 Or you can just email the reviewer e waiting for reviewer s feedback 17 4 4 Review results e There might be three kinds of results if passes reviewer should have merged your bugfix rc into your master Jenkins will automatically poll your master and do the testing merging if reviewer wants additional changes such as better naming better places to put files more source comments accompanying regression tests etc Just repeat the process do local edits local commits push to your remote branch send merge request again A third possible outcome is that reviewers may accept the commits But some additional tasks are needed in the future to improve the code e What to do next please look through the reviewer comments and try your best to address them some of the comments should indicate some mandatory changes please follow them some
69. startingPoint centerPoint Name loginName Globals Must always be fully qualified using the scope resolution operator For example mainWindow open and applicationContext getName In general the use of global variables should be avoided Instead e Place variable into a namespace e Use singleton objects Private class variables Private class variables should have underscore suffix Apart from its name and its type the scope of a variable is its most important feature Indicating class scope by using underscore makes it easy to distinguish class variables from local scratch variables For example class SomeClass private int length_ An issue is whether the underscore should be added as a prefix or as a suffix Both practices are commonly used but the latter is recommended because it seem to best preserve the 100 Naming Conventions readability of the name A side effect of the underscore naming convention is that it nicely resolves the problem of finding reasonable variable names for setter methods and constructors void setDepth int depth depth_ depth 16 6 7 Methods and Functions Names representing methods or functions MUST be verbs and written in mixed case starting with lower case to indicate what they return and procedures void methods after what they do e e g getName computeTotalWidth isEmpty A method name should avoid duplicated object name e e g line getLeng
70. that any patent claim is infringed by making using selling offering for sale or importing the Program or any portion of it 11 Patents A contributor is a copyright holder who autho rizes use under this License of the Program or a work on which the Program is based The work thus licensed is called the contributor s contribu tor version A contributor s essential patent claims are all patent claims owned or controlled by the contribu tor whether already acquired or hereafter acquired that would be infringed by some manner permit ted by this License of making using or selling its contributor version but do not include claims that would be infringed only as a consequence of further modification of the contributor version For pur poses of this definition control includes the right to grant patent sublicenses in a manner consistent with the requirements of this License Each contributor grants you a non exclusive world wide royalty free patent license under the contrib utor s essential patent claims to make use sell of fer for sale import and otherwise run modify and propagate the contents of its contributor version In the following three paragraphs a patent li cense is any express agreement or commitment however denominated not to enforce a patent such as an express permission to practice a patent or covenant not to sue for patent infringement To grant such a pa
71. to itself f L gt L is monotonic if for all x y from L x lt y gt x lt f y f BV 3 gt BV 3 f lt xl x2 x3 gt gt lt x1 1 x3 gt 24 8 Lattice Tuples Simple analyses may require complex lattices e Problem e Reaching Constants V 2 v c where v is the number of variables and c is the constants Solution e Construct a tuple of lattices where each lattice corresponds to a variable 194 integer value ICP V constant U Top Bottom 24 9 integer value ICP This is used in constant propagation Elements Top Bottom Integers Booleans e nM Bottom Bottom e n J Top Top enJn nMn n e Integers and booleans m n if m n then m M n Bottom m J n Top e The lattice has three levels the top element all other elements the bottom element e Join operation Higher level to lower level e Meet operation Lower level to higher level 24 10 Relevance to data flow analysis A lattice provides a set of flow values to a particular data flow analysis Lattices are used to argue the existence of a solution obtainable through fixed point iteration e At each program point a lattice represents an IN p or OUT p set flow value e meet merge flow values e g set union deal with control flow branches merge Top usually represents the best information initial flow value Note people can use top to represent worst base information also e The bottom value represents the worst base information
72. will make sure it is really visible and consistent with the rest of the book e please specify the how to topic is the current practice or the proposed new ways of doing things So we can have clear guideline for code review for what is mandatory and what is optional e rename three places of the pasted text with the desired page name for example ROSE Compiler Framework How to do XYZ How to do XYZ dhunparserurl ROSE Compiler Framework How to do XYZ e click save page e You will see red text trying to link to the not yet existing How to do XYZ page e click any of the red text it will bring you to an editing window to add content of your new how to page e you can now add new content and save it e Again each how to wiki page should NOT contain any level one or level two heading so it can be included at the correct levels in the print version of this wikibook 20 1 6 Insert image to wiki page e To use your own image in wiki page you have to upload the image to http commons wikimedia org 154 How to write a How to e Once you upload the image it will become public to all wikibooks users Be sure to declare your copyright if the image is created by yourself e Following this instruction to insert image and adjust the layout of your page http en wikibooks org wiki Using_Wikibooks Inserting Images 20 1 7 Rules of the content Only level three headings and higher are allowed in a how to page T
73. with clear sections and bullets e optionally you can use styles defined by w Markdown 16 9 3 Examples An example README can be found at e https github com rose compiler rose blob master projects DOpenMP_ Translator README 16 10 Source Code Documentation The source code of ROSE is documented using the Doxygen documentation system 13 http en wikipedia org wiki Markdown 14 https github com rose compiler rose 15 http www rosecompiler org ROSE_HTML_Reference index html 16 http www stack n1 dimitri doxygen 106 Source Code Documentation 16 10 1 General Guidelines e English only e Use valid Doxygen syntax see Examples below e Make the code readable for a person who reads your code for the first time e Document key concepts algorithms and functionalities e Cover your project file class namespace functions and variables e State your input and output clearly specifically the meaning of the input or output e Users are more likely to use your code if they don t have to think about what the output means or what the input should be e Clever is often synonymous with obfuscated avoid this form of cleverness in coding TODO not ready yet e Test your documentation by generating it on your machine and then manually inspecting it to confirm its correctness TODO Generating Local Documentation This does not work sometimes since we have a configuration file to indicate which directories to be s
74. www mediawiki org wiki Git Tutorial e http www mediawiki org wiki Code_review_guide e http www possibility com wiki index php title CodeReviews e http scientopia org blogs goodmath 2011 07 06 things everyone should do code review e http stackoverflow com questions 3730527 workflow for github based code review e http stackoverflow com questions 4262693 what to look for in a code review e LLNL Internal URL http github 11n1 gov e http www processimpact com articles revu_sins html Seven Deadly Sins of Soft ware Reviews 11 Chapter 18 7 on page 130 126 18 Continuous Integration ROSE s central git repository Developer s private git repository 6 auto merge 3 git fetch pull 4 git push 5 auto test 2 git commit a Figure 4 ROSE Continuous integration using Git and Jenkins Code Review Omitted for simpler explanation 18 1 Motivation Without automated continuous integration we had frequent incidents like e Developer A commits something to our central git repository s master branch The commits contain some bugs which break our build and take a long time to have a fix Then the central master branch is left to a corrupted state for weeks so nobody can check out in anything e Developer A does a lot of wonderful work offline for months But his work later is found to be incompatible with another developer s work His work has unsolvable merge conflicts 127 Continuous Integration 18 2 Overview
75. your code to see if the code implements the algorithm correctly and efficiently 16 13 Coding Correctly implement the designed documented algorithms Future users won t have time to read your code directly to discern what it does Code should be efficient in terms of both time and space memory complexity Please be aware that your translator may handle thousands of statements with even more AST nodes Be aware that people other than you may use your code or develop it further Please make this as easy as possible 16 14 Classes Try to use namespace when possible avoid global variables or classes 109 Coding Standard 16 14 1 Name Equals Functionality Name the class after what it is If you can t think of what it is that is a clue you have not thought through the design well enough e A class name should be a noun Compound names of over three words are a clue your design may be confusing various entities in your system Revisit your design Try a CRC card session to see if your objects have more responsibilities than they should 16 14 2 Explicit Access All sections public protected private should be identified explicitly Not applicable sections should be left out 16 14 3 Public Members First The parts of a class should be sorted public protected and private The ordering is most public first so people who only wish to use the class can stop reading when they reach the protected private sections
76. 16 14 4 Class Variables Class variables should NOT be declared public The concept of C information hiding and encapsulation is violated by public variables Use private variables and access functions instead One exception to this rule is when the class is essentially a data structure with no behavior equivalent to a C struct In this case it is appropriate to make the class instance variables public 16 14 5 Avoid Structs Structs are kept in C for compatibility with C only and avoiding them increases the readability of the code by reducing the number of constructs used Use a class instead 16 15 Statements 16 15 1 Loops Only loop control statements may be included in the for construction nothing else is allowed Correct sum 0 110 Statements for i 0 i lt 100 i sum value i sum valueli Incorrect for i 0 sum 0 i lt 100 i This increases maintainability and readability It also allows future developers to make a clear distinction of what controls and what is contained in the loop Loop variables should be initialized immediately before the loop 16 15 2 Type Conversions Type conversions must always be done explicitly Never rely on implicit type conversion Correct floatValue static_cast lt float gt intValue Incorrect floatValue intValue By this the programmer indicates that he is aware of the different types involved and that the mix is intenti
77. 17 17 5 Reviewer Checklist os spoor Common 120 17 6 Who should review what aooaa 123 TT What t8 3v01d Su ea rn ED Re 123 117 8 ACTICIN ar a te hk ads see AR a SES 123 17 9 Troubleshooting 2 ass 2 2 a ie aan le 124 Contents 18 19 20 21 VI 17 10 Past Software Experience o 12 11 TODO A ethers Bhi ee E A O a tee ey a 17 12 Connection to Jenkins e ee 1713 References gt eu a hee ee Path ORE Ries Continuous Integration 18 1 Motivation ace pe a EEE IRRE 18 2 Overview 2 eg aca ee I a PSs tad A Pe pet a ig ee iS 18 3 Tests on Jenkins 2 2 22 2 Common 18 4 Installed Software Packages 2 2 o e e 18 5 Check Testing Results 2 22 22 2 En En nn 18 6 Frequently Failed Jobs oaoa 18 7 Connection to Code Review oaao nn 18 87 LODO 7 2 a Ba of toh A a ee ae 18 9 References e Eee AA A Fore ee Es Frequently Asked Questions FAQ 19 1 General 1 4 2 2 2 a Da er 19 2 Compilation so 222 oce aca anne ee be ei eae E a WOES ROTE hence ee en ge ee Ge eee re Let a a Sales O 19 4 Translation aanere a a en Se cet ee A De EEN 19 9 Unpazsine ae e o ey Sk OE BRR AOD ae 19 6 Daily Worki s cuele ee Agreed ee Ghee il 19 7 Portability 2 2 een pve hae elle A Gee be el a las How tos 20 1 How to write a HOW TO 22 2 epee eG eB eS ee oe ao 20 2 How to incrementally work on a project 2 o nn nn 20 3 How to create a translator 2 2 2 oo nn 20
78. 199 199 199 200 203 203 203 203 VII Contents 29 Sandbox 207 29 1 How to create a new page e 207 29 2 How to do XYZin wiki 2 2 2 8 22288 8 2a nr na 207 29 3 How to add comments which are only visible to editor not readers of a page 208 29 4 Syntax highlighting 2 2 Co Coon nn 208 29 5 Math formula 2 2 2 2 gc tS ae En ER el 208 30 Contributors 211 List of Figures 213 31 Licenses 217 31 1 GNU GENERAL PUBLIC LICENSE 217 31 2 GNU Free Documentation License 02 2 00005 218 31 3 GNU Lesser General Public License 2 2 22 2m rn nn 219 1 About the Book FYI http wiki rosecompiler org redirects here 1 1 Goal The goal of this book is to have a community documentation providing extensive and up to date instructional information about how to use the open source ROSE compiler framework developed at Lawrence Livermore National Laboratory While the ROSE project website http www rosecompiler org already has a variety of official documentations having a wikibook for ROSE allows anybody to contribute to gathering instructional information about this software Again please note that this wikibook is not the official documentation of ROSE It is the community efforts contributed by anyone just like you 1 2 How To Contribute If you want to contribute check to make sure your contributions to the wikibook are relevant to this wikibook about ROSE e Welc
79. 2 0 License http creativecommons org licenses by 2 0 e cc by 2 0 Creative Commons Attribution 2 0 License http creativecommons org licenses by 2 0 deed en e cc by 2 5 Creative Commons Attribution 2 5 License http creativecommons org licenses by 2 5 deed en e cc by 3 0 Creative Commons Attribution 3 0 License http creativecommons org licenses by 3 0 deed en e GPL GNU General Public License http www gnu org licenses gpl 2 0 txt e LGPL GNU Lesser General Public License http www gnu org licenses lgpl html e PD This image is in the public domain e ATTR The copyright holder of this file allows anyone to use it for any purpose provided that the copyright holder is properly attributed Redistribution derivative work commercial use and all other use is permitted e EURO This is the common reverse face of a euro coin The copyright on the design of the common face of the euro coins belongs to the European Commission Authorised is reproduction in a format without relief drawings paintings films provided they are not detrimental to the image of the euro e LFK Lizenz Freie Kunst http artlibre org licence lal de e CFR Copyright free use 213 List of Figures e EPL Eclipse Public License http www eclipse org org documents epl v10 php Copies of the GPL the LGPL as well as a GFDL are included in chapter Licenses Please note that images in the public domain do not require attri
80. 5 6 204 80 connected HTTP request sent awaiting response 404 Not Found 2013 02 15 17 26 42 ERROR 404 Not Found make 3 roseBinaryEDG 3 3 x86_64 pc linux gnu GNU 4 3 tar gz Error 1 make 3 Leaving directory global project projectdirs rosecompiler rose project workspace xomp instr buildtree src frontend CxxFrontend make 2 all recursive Error 1 make 2 Leaving directory global project projectdirs rosecompiler rose project workspace xomp instr buildtree src frontend CxxFrontend make 1 all recursive Error 1 make 1 Leaving directory global project projectdirs r osecompiler rose project workspace xomp instr buildtree src frontend make all recursive Error 1 make Leaving directory global project proj ectdirs rosecompiler rose project workspace xomp instr buildtree src Solution add an official rose repo as an additional remote repo of your local repo e add a canonical repository like the one at github git add remote official rose https github com rose compiler rose git e git fetch official rose to retrieve hash numbers etc in the canonical repository e Now you can build rose again it should find the canonical repo you just added and use it to find a matching EDG binary 19 2 2 How to access EDG or EDG SAGE connection code From page 5 of http rosecompiler org ROSE_UserManual ROSE UserManual pdf The connection code that was used to translate EDG s AST to SAGE I
81. 5 cs tamu edu slides keynote pdf 199 Good API Design 26 3 General Principles e When in doubt leave it out You can always add but you can never remove e Just because you can doesn t mean you should e Power to weight ratio http en wikipedia org wiki Power to weight_ratio gt A measurement of actual performance power weight Don t give users a gun to shoot themselves with e Information hiding minimize the accessibility of everything 26 3 1 Documentation Matters e Class what an instance represents Method contract between method and calling client preconditions postconditions and side effects Parameter indicate units form ownership Pre and Post Conditions e The precondition statement indicates what must be true before the function is called e The postcondition statement indicates what will be true when the function finishes its work post lt return_value gt empty false 26 3 2 API vs Implementation Implementation details should not impact the API Don t let implementation details leak into the API Performance e Design for usability refactor for performance e Do not warp the API to gain performance e Effects of API design decisions on performance are real and permanent e Component getSize returns Dimension e Dimension is mutable e Each getSize call must allocate Dimension e Causes millions of needless object allocations 2
82. 6 3 3 Harmonize e API must coexist peacefully with platform e Do what is customary standard 200 General Principles e Avoid obsolete parameter and return types e Mimic patterns in core APIs and language e Take advantage of API friendly features generics varargs enums default arguments e Don t make the client do anything the module could do e Reduce need for boilterplate code e Don t violate the Principle of Least Astonishment http en wikipedia org wiki Principle_of_least_astonishment gt The design should match the user s experience expectations and mental models aims to exploit users pre existing knowledge as a way to minimize the learning curve e Provide programmatic access to all data available in string form gt no client string parsing necessary e Overload with care ambiguous overloadings 26 3 4 Names Matter e Largely self explanatory avoid cryptic abbreviations e Be consistent e g same word means same thing e Strive for symmetry e Should read like prose http en wikipedia org wiki Prose gt T he most typical form of language applying ordinary grammatical structure and natural flow of speech rather than rhythmic structure as in traditional poetry if car speed gt 2 SPEED_LIMIT generateAlert Watch out for cops 26 3 5 Input Parameters e interface types over classes flexibility performance e most specific possible type moves
83. 9 Virtual CFG of ROSE tutorial pdf e Source Files e src frontend Sagelll virtualCFG virtualCFG h e src frontend Sagelll virtualCFG virtualCFG C not only give definitions of virtual CFG h but also extend AST node support in VirtualCFG e src ROSETTA Grammar Statement code prototypes of member functions for SgStatement nodes etc e src ROSETTA Grammar Expression code prototypes of member functions for SgExpression nodes etc e src ROSETTA Grammar Support code prototypes of member functions for SgIni tialized LocatedNode nodes etc e src ROSETTA Grammar Common code prototypes of member functions for other nodes etc e src frontend Sagelll virtualCFG memberFunctions C implementation of virtual CFG related member functions for each AST node 1 http www rosecompiler org ROSE_Tutorial ROSE Tutorial pdf 39 Program Analysis e This file will help the generation of buildTree src frontend SagelII Cxx_ Grammar h e Test directory tests CompileTests virtualCFG _tests e A dot graph generator generate a dot graph for either the raw or interesting virtual CFG e Source tests CompileTests virtualCFG_tests generateVirtualCFG C e Installed under rose_ins bin How to extend VirtualCFG to support OpenMP e how to add CFGNode for SgOmpClause in e 1 Identify the class name in ROSETTA in frontend For example if SgOmpPrivateClause or SgOmpSharedClause are not support in VirtualCFG it is necessary to check whether buildT
84. Analysis https mailman nersc gov pipermail rose public 2010 September 000390 html On 9 1 10 11 49 AM Fredrik Kjolstad wrote gt Hi all gt gt I am trying to use Rose as the analysis backend for a refactoring gt engine and for one of the refactorings I am implementing I need gt whole program pointer analysis Rose has an implementation of gt steensgard s algorithm and I have some questions regarding how to use gt this gt gt I looked at the file steensgaardTest2 C to figure out how to invoke gt this analysis and I am a bit perplexed v gt 1 The file SteensgaardPtrAnal h that is included by the test is not gt present in the include directory of my installed version of Rose gt Does this mean that the Steensgaard implementation is not a part of gt the shipped compiler or does it mean that I have to retrieve an gt instance of it through some factory method whose static return type is gt PtrAnal I believe it is in the shipped compiler And you re using the correct file to figure out how to use it It should be in the installed include directory if it is not it s probably something that needs to be fixed But you can copy the include file from ROSE src midend programAnalysis pointerAnal as a temporary fix gt 2 How do I initialize the alias analysis for a given SgProject Is gt this done through the overloaded The steensgaardTest2 C file shows how to set up ever
85. Analysis IntraProceduralAnalysis intraDataflowAnalysis InterProceduralDataflow intraDataflowAnalysis the transfer function that is applied to SgFunctionCallExp nodes to perform the appropriate state transfers fw true if this is a forward analysis and false if this is a backward analysis n the dataflow node that is being processed state the NodeState object that describes the dataflow 70 How to use one analysis state immediately before if fw true or immediately after if fw false the SgFunctionCallExp node as established by earlier analysis passes dfInfo the Lattices that this transfer function operates on The function propagates them to the calling function and overwrites them with the dataflow result of calling this function retState Pointer reference to a Lattice vector that will be assigned to point to the lattices of the function call s return value The callee may not modify these lattices Returns true if any of the input lattices changed as a result of the transfer function and false otherwise bool transfer const Function amp func const DataflowNode amp n NodeState amp state const std vector lt Lattice gt amp dfInfo std vector lt Lattice gt retState bool fw return false void runAnalysis 3 simply call intra procedural analysis on each function one by one void UnstructuredPassInterDataflow runAnalysis set
86. Definitions This License refers to version 3 of the GNU Gen eral Public License Copyright also means copyright like laws that ap ply to other kinds of works such as semiconductor masks The Program refers to any copyrightable work licensed under this License Each licensee is ad dressed as you Licensees and recipients may be individuals or organizations To modify a work means to copy from or adapt all or part of the work in a fashion requiring copy right permission other than the making of an exact copy The resulting work is called a modified ver sion of the earlier work or a work based on the earlier work A covered work means either the unmodified Pro gram or a work based on the Program To propagate a work means to do anything with it that without permission would make you directly or secondarily liable for infringement under appli cable copyright law except executing it on a com puter or modifying a private copy Propagation in cludes copying distribution with or without mod ification making available to the public and in some countries other activities as well To convey a work means any kind of propagation that enables other parties to make or receive copies Mere interaction with a user through a computer network with no transfer of a copy is not convey ing An interactive user interface displays Appropriate Legal Noti
87. E_VisitorPatternDefaultBase protected Common arguments to the underlying transfer function const Function amp func which function are we talking about const DataflowNode amp dfNode wrapper of CFGNode NodeState amp nodeState lattice element state context information const std vector lt Lattice gt amp dfInfo data flow information 6 http en wikibooks org wiki Data_flow_analysis 23flow 2Ftransfer_function 55 Generic Dataflow Framework public IntraDFTransferVisitor const Function amp f const DataflowNode amp n NodeState amp s const std vector lt Lattice gt amp d func f dfNode n nodeState s dfInfo d virtual bool finish 0 virtual IntraDFTransferVisitor 1 Fs class LiveDeadVarsTransfer public IntraDFTransferVisitor F class ConstantPropagationAnalysisTransfer public VariableStateTransfer lt ConstantPropagationLattice gt 11 5 1 Constant Propagation template lt class LatticeType gt class VariableStateTransfer public IntraDFTransferVisitor 3 class ConstantPropagationAnalysisTransfer public VariableStateTransfer lt ConstantPropagationLattice gt void ConstantPropagationAnalysisTransfer visit SgIntVal sgn ROSE_ASSERT sgn NULL ConstantPropagationLattice resLat getLattice sgn ROSE_ASSERT resLat NULL resLat gt setValue sgn gt get_value resLat gt setLevel ConstantPropagationLattice constantValue
88. Expressions Guidelines for readability simplicity and debuggability e Ternary operators should be replaced with if else e Long expressions should be broken up into several simpler statements Add assertion for each pointer value obtained along the process to assist later debugging e Clever use of operator precedence shortcut evaluation assignment expressions etc should be rewritten to easy to understand alternative forms e Always remember that future programmers will appreciate clear and simple code rather than obfuscated cleverness 16 17 AST Translators All ROSE based translators should call AstTests runAllTests project after all the transfor mation is done to make sure the translated AST is correct This has a higher standard than just correctly unparsed to compilable code It is common for an AST to go through unparsing correctly but fail on the sanity check More information is at Sanity_ check 16 18 References We list some external resources which are influential for us to define ROSE s coding standard e http www possibility com Cpp CppCodingStandard html 17 Chapter 8 1 on page 31 113 Coding Standard e Sutter and Alexandrescu C Coding Standards 220 pgs Addison Wesley 2005 ISBN 0 321 11358 6 e http www parashift com c faq coding standards html e http geosoft no development cppstyle htm1 e http google styleguide googlecode com svn trunk cppguide xml 114 17 Code Re
89. H 23Watching pages Wikibook Writing Tips e Preferences gt Watchlist gt Advanced options gt you can select the options you want such as Add pages I edit to my watchlist and Add pages I create to my watchlist e you can also individually watch and unwatch any wiki page by click on the star on the page s tab list after View history Caveat we don t know if wikibooks supports users to watch one entire book So far you have to do this one page after another by editing them at some points 1 4 Wikibook Writing Tips 1 What exactly is BookCat for It is a category tag automatically added by wiki robot scripts 2 Should BookCat be at the end of the document Any position in the page should be fine Having it at top may be better so it won t be accidentally deleted when we add new things at the bottom 2 ROSE s Documentations ROSE uses a range of materials to document the project Static content of ROSE web http rosecompiler org index html e ROSE manual the design algorithm and implementation details Written in LaTeX the content of the manual can come from published papers It may contain intense academic citations and math formula e ROSE tutorial short code examples for tools built on top of ROSE step by step instructions for doing things Tightly integrated into ROSE s build system so each example is always verified to work with ROSE e Doxygen web reference class namespace references of source code W
90. II was derived loosely from the EDG C source generator and has formed the basis of the SAGE III translator from EDG to SAGE III s IR Under the license we have the EDG source code and the translation from the EDG AST in distributions are excluded from source release and are made available through a binary format No part of the EDG work is visible to the user of ROSE The EDG source are available only to those who have the EDG research or commercial license Chapter 2 6 Getting a Free EDG License for Research Use of the manual has instructions about how to obtain the EDG license Once you obtain the license please contact the staff members of ROSE to verify your license After that they will give you more instructions about how to proceed 139 Frequently Asked Questions FAQ 19 2 3 How to speedup compiling ROSE Question It takes hours to compile ROSE how can I speed up this process Answer e if you have multi core processors try to use make j4 make by using four processes or even more if you like e also try to only build librose so under src by typing make C src j4 e Or only try to build the language support you are interested in during configure such as e sourcetree configure enable only c if you are only interested in C C support e sourcetree configure enable only fortran if you are only interested in Fortran support e sourcetree configure help show all other options to enable only a
91. In addition you must do these things in the Modi fied Version A Use in the Title Page and on the covers if any a title distinct from that of the Document and from those of previous versions which should if there were any be listed in the History section of the Document You may use the same title as a previous version if the original publisher of that version gives permission B List on the Title Page as authors one or more persons or entities responsible for authorship of the modifications in the Modified Version together with at least five of the principal authors of the Document all of its principal authors if it has fewer than five unless they release you from this requirement C State on the Title page the name of the publisher of the Modified Version as the publisher D Preserve all the copyright notices of the Document E Add an appropriate copyright notice for your modifica tions adjacent to the other copyright notices F Include immediately after the copyright notices a license notice giving the public permission to use the Modified Version under the terms of this Li cense in the form shown in the Addendum below G Preserve in that license notice the full lists of In variant Sections and required Cover Texts given in the Document s license notice H Include an unal tered copy of this License I Preserve the section Entitled History Preserve its Title and add to it an item stat
92. Jenks ross Koss ee ee ia Eee Git 23 1 Introduction 3 64 4 a Ne fete Aceh LE a a 23 2 git 1 7 10 or later for github com N nn nn 23 3 Converting from a Subversion user 2 2 2 22mm e 234 Gil Convention oa a te ee A A 23 02 PUSO E 23 07 Rebase it eee eee ae A Re a ee eRe SES 23 7 References RANAS Taoist ete oe RE ah Ge 2 Lattices 24 1 Introduction 2 rr AS Bog eas Bo eo As wok A Boe 242 Poseti ze an Grea i BO A EI ae ee aS a ee em ESOS 24 53 Lattiee Definition cis o ooh hoe Hee Se en et a GE Ae ho bs 24 4 Infinite vs Finite lattices 2 2 Co Hmmm 24 5 Example Bit vector Lattices 2 2 2 Co Eon 24 6 Monotonic Functions 2AT Examples na 2 au dan ae a BE an 24 8 attics ples rio do ee DEN Ba ee 24 97 Integer Value ICR 2 22 Ep er Ben 24 10 Relevance to data flow analysis 2 2 Comm C Programming Good API Design 26 1 Characteristics of a Good API 222 2 En nn nn 26 2 The Process of API Design 2 En e 20 3 General Principles sai aa eo a a ER Re ie eae hee Be Who is using ROSE 27 1 Universities d 02 0 A a RN 27 2 DOE national laboratories u ea e a a opie ana K ona 21 3 COMPaniS e ars ge aoi Gs wes ou eee hae seen TODO List 28 1 How to backup mirror this wikibook o 28 2 Maintain the print version 2 2 22 Coon nn 28 3 Maintain the better pdf file 2 CC CE on nn 28 4 Documentation Alternatives 197
93. Li cense and replace the individual copies of this Li cense in the various documents with a single copy that is included in the collection provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects You may extract a single document from such a col lection and distribute it individually under this Li cense provided you insert a copy of this License into the extracted document and follow this Li cense in all other respects regarding verbatim copy ing of that document 7 AGGREGATION WITH INDEPENDENT WORKS A compilation of the Document or its derivatives with other separate and independent documents or works in or on a volume of a storage or distribution medium is called an aggregate if the copyright re sulting from the compilation is not used to limit the legal rights of the compilation s users beyond what the individual works permit When the Document is included in an aggregate this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document If the Cover Text requirement of section 3 is appli cable to these copies of the Document then if the Document is less than one half of the entire aggre gate the Document s Cover Texts may be placed on covers that bracket the Document within the aggregate or the electronic equivalent of covers if the Document is in electronic form Otherwise they must appear on
94. N VS ites m EN E SS a u EL i prama tion zen JA XA N lt gt lt gt L S nn hee ciar Figure 6 C SgForStatement 162 How to set up the makefile for a translator Fortran uses SgFortranDo for the do loops TT i f origiaalExpeessionTree operatorPosition operaiorPonition type_table arent parese ths_operand i on ioaTive opera expression type ty ie MA lt oo y aa foiinaxpreaiaTree operacion frat ginalEprssica Tice pres a Figure 7 Fortran SgFortranDo 20 6 3 Implement the translation functions e Use the wholeAST as reference to implement the translation function e Generate the new AST node by copy required information from the original AST node e Remove the original node and make sure the parent child relationship in AST is setup properly 20 6 4 Testing output code e If compiler is available to test the output code run the backend to generate object by the backend compiler e If compiler is not available for the target language make sure output codes can be generated from the testing cases It is suggested to run the compilation tests for all the testing output 20 7 How to set up the makefile for a translator In this How to you will create a makefile to compile and test your own custom ROSE translator You may want to first look at How to install ROSE ROSE Compiler Fr
95. RIGHT HOLD ERS AND OR OTHER PARTIES PROVIDE THE PROGRAM AS IS WITHOUT WARRANTY OF ANY KIND EITHER EXPRESSED OR IMPLIED INCLUDING BUT NOT LIMITED TO THE IM PLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU SHOULD THE PROGRAM PROVE DEFEC TIVE YOU ASSUME THE COST OF ALL NECES SARY SERVICING REPAIR OR CORRECTION 16 Limitation of Liability IN NO EVENT UNLESS REQUIRED BY APPLI CABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER OR ANY OTHER PARTY WHO MODIFIES AND OR CON VEYS THE PROGRAM AS PERMITTED ABOVE BE LIABLE TO YOU FOR DAMAGES IN CLUDING ANY GENERAL SPECIAL INCIDEN TAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM INCLUDING BUT NOT LIM ITED TO LOSS OF DATA OR DATA BEING REN DERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES 17 In terpretation of Sections 15 and 16 If the disclaimer of warranty and limitation of lia bility provided above cannot be given local legal ef PDF produced by some word processors for output purposes only The Title Page means for a printed book the title page itself plus such following pages as are needed to hold legibly the material this License requires to appe
96. ROSE Compiler Framework Wikibooks org March 17 2013 On the 28th of April 2012 the contents of the English as well as German Wikibooks and Wikipedia projects were licensed under Creative Commons Attribution ShareAlike 3 0 Unported license An URI to this license is given in the list of figures on page 213 If this document is a derived work from the contents of one of these projects and the content was still licensed by the project under this license at the time of derivation this document has to be licensed under the same a similar or a compatible license as stated in section 4b of the license The list of contributors is included in chapter Contributors on page 211 The licenses GPL LGPL and GFDL are included in chapter Licenses on page 217 since this book and or parts of it may or may not be licensed under one or more of these licenses and thus require inclusion of these licenses The licenses of the figures are given in the list of figures on page 213 This PDF was generated by the IAT X typesetting software The LATEX source code is included as an attachment source 7z txt in this PDF file To extract the source from the PDF file we recommend the use of http www pdflabs com tools pdftk the pdf toolkit utility or clicking the paper clip attachment symbol on the lower left of your PDF Viewer selecting Save Attachment After extracting it from the PDF file you have to rename it to source 7z To uncompress the resulting archive we recommen
97. When you convey a copy of a covered work you may at your option remove any additional permissions from that copy or from any part of it Additional permissions may be written to require their own re moval in certain cases when you modify the work You may place additional permissions on material added by you to a covered work for which you have or can give appropriate copyright permission Notwithstanding any other provision of this Li cense for material you add to a covered work you may if authorized by the copyright holders of that material supplement the terms of this License with terms a Disclaiming warranty or limiting liability dif ferently from the terms of sections 15 and 16 of this License or b Requiring preservation of specified reasonable legal notices or author attributions in that material or in the Appropriate Legal Notices displayed by works containing it or c Prohibit ing misrepresentation of the origin of that material or requiring that modified versions of such material be marked in reasonable ways as different from the original version or d Limiting the use for pub licity purposes of names of licensors or authors of the material or e Declining to grant rights under trademark law for use of some trade names trade marks or service marks or f Requiring indem nification of licensors and authors of that material by anyone who conveys the material or modified versions of it with contra
98. a developer works on ROSE they generally clone from this central location and when they ve made changes they generally push those changes back to the same central location 186 Git Convention 23 4 Git Convention 23 4 1 Name and Email Before you commit your local changes you MUST ensure that you have correctly configured your author and email information on all of your machines Having a recognizable and consistent name and email will make it easier for us to evaluate the contributions that you ve made to our project Guidelines e Name You MUST use your official name you commonly use for work business not nickname or alias which cannot be easily recognized by co workers managers or sponsors e Email You MUST use your email commonly used for work It can be either your company email or your personal email gmail if you DO commonly use that personal email for business purpose To check if your author and email are configured correctly git config user name lt your name gt git config user email lt your email gt Alternatively you can just type the following to list all your current git configuration variables and values including name and email information git config 1 To set your name and email git config global user name lt Your Name gt git config global user email lt your email com gt 8 8 8 y 23 4 2 Branch Naming Convention All developer central repository branches shou
99. a partial order Given a poset there may exist an infimum or a supremum However not all posets contain these Given a poset P with set X and order lt An infimum of a subset S of X is an element a of X such that e a lt z for all x in Sand e for all y in X if for all x in S y lt x then y lt a The dual of this notion is the supremum which has the definition of infimum if you switch lt with gt If we simply pick an element of X that satisfies the first condition we have a lower bound The second condition ensures that we have if it exists the unique greatest lower bound Similarly for suprema 191 Lattices A lattice is a particular kind of poset In particular a lattice L is a poset P X lt where For any two elements of the lattice a and b the set a b has a join and a meet The join and meet operations MUST satisfy the following conditions e 1 The join and meet must commute e 2 The join and meet are associative e 3 The join and meet are idempotent that is x join itself or x meet itself are both x If the lattice contains a meet it is a meet semilattice if a lattice contains a join it is a join semilattice similarly there exists a meet semilattice Definitions obtained from wikipedia with minimal modification 24 3 Lattice Definition Definition of a Lattice L A V e Lisa poset under lt such that e Every pair of elements has a unique greatest lower bound meet and least upper bound join
100. adVarAnalysis C 228 1 0x00002aaaac3d9968 in SgAssignOp accept this 0xa20320 visitor at Cxx_Grammar C 143069 2 0x00002aaaadc61c04 in LiveDeadVarsTransfer visit this 0xaf9e00 sgn 0xa20320 at sourcetree src midend pro gramAnalysis genericDataflow simpleAnalyses liveDeadVarAnalysis C 384 3 0x00002aaaadbbaef0 in ROSE_VisitorPatternDefaultBase visit this 0xaf9e00 variable_SgBinaryOp 0xa20320 at srce frontend SageIII Cxx_Grammar h 316006 4 0x00002aaaadbba04a in ROSE_VisitorPatternDefaultBase visit this 0xaf9e00 variable_SgAssign0p 0xa20320 at srce frontend SageIII Cxx_Grammar h 315931 5 0x00002aaaac3d9968 in SgAssignOp accept this 0xa20320 visitor at Cxx_Grammar C 143069 6 0x00002aaaadbcca0a in IntraUniDirectionalDataflow runAnalysis this 0x7fffffffA9f0 func fState 0xafbd18 analyzeDueToCallers true calleesUpdated at sourcetr ee src midend programAnalysis genericDataflow analysis dataflow C 282 7 0x00002aaaadbbf444 in IntraProceduralDataflow runAnalysis this 0x7fffffffda00 func state 0xafbd18 at sourcet ree src midend programAnalysis genericDataflow analysis dataflow h 74 8 0x00002aaaadbb0966 in UnstructuredPassInterDataflow runAnalysis this 0x7fffffffda50 at sourcetr ee src midend programAnalysis genericDataflow analysis analysis C 467 9 0x000000000040381a in main argc 2 argv 0x7fffffffdba8 at sourcetre
101. ail on the sanity check The recommend sanity check is AstTests runAllTests project from src midend astDiagnostics Internally it calls the following checks e TestAstForProperlyMangledNames e TestAstCompilerGeneratedNodes e AstTextAttributesHandling e AstCycleTest e TestAstTemplateProperties e TestAstForProperlySetDefiningAndNondefiningDeclarations TestAstSymbolTables e TestAstAccessToDeclarations e TestExpressionTypes e TestMangledNames test e TestParentPointersInMemoryPool test e TestChildPointersInMemoryPool test TestMappingOfDeclarationsInMemoryPoolToSymbols test e TestLValueExpressions e TestMultiFileConsistancy test 2009 e TestAstAccessToDeclarations test i named type test There are some other functions floating around But they should be merged into Ast Tests runAllTests project e FixSgProject project in Qing s AST interface e Utility sanityCheck SgProject e Utility consistencyCheck SgProject SgFile 31 Abstract Syntax Tree Intermediate Representation 8 2 Visualization of AST We provide ROSE_INSTALLATION_TREE bin dotGeneratorWholeASTGraph complex graph and dotGenerator a simpler version to generate a dot graph of the detailed AST of input code To visualize the generated dot graph you have to install e ZGRViewer here http zvtm sourceforge net zgrviewer html download e Graphviz http www graphviz org Download php A complete example make su
102. al ROSE Tutorial pdf Chapter 29 Handling Comments Preprocessor Directives And Adding Arbitrary Text to Generated Code 8 5 AST Construction SageBuilder and SageInterface namespaces provide functions to create ASTs and manipulate them 33 9 Program Translation With its high level intermediate representation ROSE is suitable for building source to source translators This is achieved by re structuring the AST of the input source code then unparsing the transformed AST to the output source code 9 1 Documentation Official tutorial Chapter 32 AST Construction of ROSE Tutorial http rosecompiler org ROSE_Tutorial ROSE Tutorial pdf Many beginners questions should be readily answered after reading this chapter 9 2 Expected behavior of a ROSE Translator A translator built using ROSE is designed to act like a compiler gcc g gfortran etc depending on the input file types So users of the translator only need to change the build system for the input files to use the translator instead of the original compiler 9 3 SageBuilder and Sagelnterface The official guide for restructuring constructing AST highly recommends using helper functions from SageBuilder and Sagelnterface namespaces to create AST pieces and moving them around These helper functions try to be stable across low level changes and be smart enough to transparently set many edges and maintain symbol tables Users who want to have lower level control
103. all directly within that overall sub ject Thus if the Document is in part a textbook of mathematics a Secondary Section may not ex plain any mathematics The relationship could be a matter of historical connection with the subject or with related matters or of legal commercial philosophical ethical or political position regard ing them The Invariant Sections are certain Secondary Sec tions whose titles are designated as being those of Invariant Sections in the notice that says that the Document is released under this License If a sec tion does not fit the above definition of Secondary then it is not allowed to be designated as Invariant The Document may contain zero Invariant Sections If the Document does not identify any Invariant Sections then there are none The Cover Texts are certain short passages of text that are listed as Front Cover Texts or Back Cover Texts in the notice that says that the Document is released under this License A Front Cover Text may be at most 5 words and a Back Cover Text may be at most 25 words A Transparent copy of the Document means a machine readable copy represented in a format whose specification is available to the general pub lic that is suitable for revising the document straightforwardly with generic text editors or for images composed of pixels generic paint programs or for drawings some widely available drawing ed itor and that is suitable for input to text
104. all its users We the Free Software Foundation use the GNU General Public License for most of our software it applies also to any other work released this way by its authors You can apply it to your programs too When we speak of free software we are referring to freedom not price Our General Public Li censes are designed to make sure that you have the freedom to distribute copies of free software and charge for them if you wish that you receive source code or can get it if you want it that you can change the software or use pieces of it in new free programs and that you know you can do these things To protect your rights we need to prevent others from denying you these rights or asking you to sur render the rights Therefore you have certain re sponsibilities if you distribute copies of the soft ware or if you modify it responsibilities to respect the freedom of others For example if you distribute copies of such a pro gram whether gratis or for a fee you must pass on to the recipients the same freedoms that you re ceived You must make sure that they too receive or can get the source code And you must show them these terms so they know their rights Developers that use the GNU GPL protect your rights with two steps 1 assert copyright on the software and 2 offer you this License giving you legal permission to copy distribute and or modify it For the developers and authors protection the
105. als 15 5 1 Review criteria 90 Optimize e Optimize our workflow to allow us to do more quality and use less time and other resources e Address what is slowing us down or distracting us e Simplify daily life Compare how we can eliminate or automate using the proposed workflow improvements e It is counterproductive to improve workflow by adding more hoops steps clicks into daily work Improve e Allows the improvement of the quality of work incrementally e Accepting incremental improvements is more realistic than asking for perfection in the first try e Workflow should allow quick new contributions and fast revision of existing contribu tions Automate e Additions to the workflow should be automated as much as possible Preserve e It must preserve existing work e No creation of anything from scratch e Does it interact well with existing workflow e Is there a way to convert existing code documents into the new form Simplicity e The more software tools we depend on the harder to use and maintain our workflow Similarly the more formats standards we enforce the harder for developers to do their daily work e Adopting new required software components and new required technical formats stan dards in our workflow should be very carefully reviewed for the associated long term benefits and costs Long term means the range of 5 to 10 years and is not tied toa temporary thing we use now Preference of major contributors
106. amework Installa tion 3 Chapter 4 on page 15 163 How tos 20 7 1 Environment variables You must have the proper environment variable set so you translator can find the librose so during execution export LD_L IBRARY_PATH ROSE_INSTALL 1ib BOOST_INSTALL 1ib LD_LIBRARY_PATH 20 7 2 Translator Code Here is a simplest ROSE translator ROSE translator example identity translator No AST manipulations just a simple translation input_code gt ROSE AST gt output_code include lt rose h gt int main int argc char argv ae Build the AST used by ROSE SgProject project frontend argc argv Run internal consistency tests on AST AstTests runAllTests project Insert your own manipulations of the AST here Generate source code from AST and invoke your desired backend compiler return backend project 20 7 3 Makefile Here is a sample makefile Please make sure replacing some leading spaces of make rules with leading Tabs if you copy amp paste this sample A sample Makefile to build a ROSE tool Important remember that Makefile rules must contain tabs lt target gt lt dependency gt lt TAB gt lt command gt lt endl gt Please replace space with TAB if you copy amp paste this file to create your Makefile ROSE installation contains libraries e g librose la headers e g rose
107. anTests LANL_POP pop distro tests RunTests FortranTests LANL_POP netcdf 4 1 1 libcf tests CompileTests ElsaTestCases sre ROSETTA src 3rdPartyLibraries qrose projects DatalogAnalysis projects backstroke Licenselnformation docs Rose AstProcessing To list files based on size 136 Compilation find type f printO xargs 0 ls s sort k1 1rn 241568 git objects pack pack f366503d291fc33cb201781e6414688390e7f309 pack 13484 tests CompileTests RoseExample_tests Cxx_Grammar h 10240 projects traceAnalysis vmp hw part trace 6324 tests RunTests FortranTests LANL_POP_OLD poptest tgz 5828 winspecific MSVS_ROSE Debug MSVS_ROSETTA pdb 4732 git objects pack pack f3665034291fc33cb201781e6414688390e7f309 idx 4488 binaries samples bgl helloworld mpicc 4488 binaries samples bgl helloworld mpixlc 4080 LicenseInformation edison_group pdf 3968 projects RTC tags 3952 src frontend Disassemblers x86 InstructionSetReference NZ pdf 3908 tests CompileTests RoseExample_tests trial_Cxx_Grammar C 3572 winspecific MSVS_project_ROSETTA_empty MSVS_project_ROSETTA_empty ncb 3424 src frontend Disassemblers x86 InstructionSetReference AM pdf 2868 git index 2864 projects compassDistribution COMPASS_SUBMIT tar gz 2864 projects COMPASS_SUBMIT tar gz 2740 ROSE_ResearchPapers 2007 Communi catingSoftwareArchitectureUsingAUnifiedSingle ViewVisualization ICECC S pdf 2592
108. analyzeDueToCallers std set lt Function gt calleesUpdated protected 60 Analysis Driver bool propagateStateToNextNode const std vector lt Lattice gt amp curNodeState DataflowNode curDFNode int nodelndex const std vector lt Lattice gt amp nextNodeState DataflowNode nextDFNode std vector lt DataflowNode gt gatherDescendants std vector lt DataflowEdge gt edges DataflowNode DataflowEdge edgeFn const virtual NodeState initializeFunctionNodeState const Function amp func NodeState fState 0 virtual VirtualCFG dataflow getInitialWorklist const Function amp func bool firstVisit bool analyzeDueToCallers const set lt Function gt amp calleesUpdated NodeState fState 0 virtual vector lt Lattice gt getLatticeAnte NodeState state 0 virtual vector lt Lattice gt getLatticePost NodeState state 0 If we re currently at a function call use the associated inter procedural analysis to determine the effect of this function call on the dataflow state virtual void transferFunctionCall const Function amp func const DataflowNode amp n NodeState state 0 virtual vector lt DataflowNode gt getDescendants const DataflowNode amp n 0 virtual DataflowNode getUltimate const Function amp func 0 ultimate what final CFG node 33 class IntraBWDataflow public IntraUniDirectionalDataflow BW Backward public IntraBWDataflow NodeStat
109. and added to the Pull Request before the code review can be completed 2 Recommended the details of the comment could represent a best practice or simply it could be intended to provide some insight to the developer that they may have not thought about Both Mandatory and Recommended can be accompanied by the keyword Nitpick 3 Nitpick the details of the comment represent a fix that usually involves a spelling grammatical or coding style correction The main purpose of the nitpick indication is to let the developer know that you re not trying to be on their case and make their life difficult but an error is an error or there s a better way to do something 17 5 3 Decisions Make a clear and definitive decision for the code review e Pass The code does what it is supposed to do with clear documentation and test cases Merge and close the pull request e Pass but with future tasks The commits are accepted But some additional tasks are needed in the future to improve the code They can be put into a separate set of commits and pushed later on e Fail Additional work is needed such as better naming better places to put files more source comments add regression tests etc Notify the developers of the issues and ask for a new set of commits to be pushed addressing the corrections or improvements 17 5 4 Giving negative feedback We directly quote from http www mediawiki org wiki Code_review_guide Giving_ negative_feedback
110. and e things which are not yet handled by the current implementation switch type gt variantT case V_SgTypeDouble break case V_SgTypelnt break case V_SgTypeFloat things which are known to be allowed to be ignored break default Things which are not yet explicitly handled cerr lt lt warning unhandled node type lt lt type gt class_name lt lt endl 16 15 6 assert It is encouraged to use assert often to explicitly express and guarantee assumptions used in the code Please use ROSE_ASSERT or assert For each occurrence of assertion you MUST add a printf or cerr message to indicate where in the code and what goes wrong so users can immediately know the cause of the assertion failure without going through a debugger to find out what went wrong 112 Expressions 16 15 7 Statements To Be Avoided The following statements should usually be avoided e Goto statements should not be used Goto statements violate the idea of structured code There are very few cases for instance breaking out of deeply nested structures where goto should be considered and only if the equivalent structured counterpart is less readable e Executable statements in conditionals should be avoided Conditionals with executable statements are very difficult to read File fileHandle open fileName w if fileHandle gt NOT if fileHandle open fileName w 16 16
111. and any other pertinent obligations then as a consequence you may not convey it at all For example if you agree to terms that obligate you to collect a roy alty for further conveying from those to whom you convey the Program the only way you could satisfy both those terms and this License would be to re frain entirely from conveying the Program 13 Use with the GNU Affero General Public License 31 2 GNU Free Documentation License Version 1 3 3 November 2008 Copyright 2000 2001 2002 2007 2008 Free Soft ware Foundation Inc lt http fsf org gt Everyone is permitted to copy and distribute verba tim copies of this license document but changing it is not allowed 0 PREAMBLE The purpose of this License is to make a manual textbook or other functional and useful document free in the sense of freedom to assure everyone the effective freedom to copy and redistribute it with or without modifying it either commercially or noncommercially Secondarily this License pre serves for the author and publisher a way to get credit for their work while not being considered responsible for modifications made by others This License is a kind of copyleft which means that derivative works of the document must them selves be free in the same sense It complements the GNU General Public License which is a copy left license designed for free software We have designed this License in order to use it for manuals for fr
112. and warning messages optional 95 Coding Standard Performance MUST have complexity analysis Estimate the time and space complexity of this module so users can know what to expect Reliability Optional Related work cite relevant work in textbooks and papers 16 3 6 Development guidelines Coding guidelines standards and conventions Standard languages and tools Definitions of variables and a description of where they are used 16 3 7 References A good resource is the SoftWare Improvement Networking Group SWING at LLNL https swing 11n1 gov http www ehow com how_6734245_write software design document html ixzz22E1xFTCS http www ehow com how_6082541_write analysis design document software html http technet microsoft com en us library cc506047 http gcc gnu org wiki http gec gnu org wiki StructureDfGCC http gcc gnu org onlinedocs gccint index htmltTop 16 3 8 TODO a sample design document 16 4 Testing Rules 96 All contributions MUST have the accompanying test translator and input files to demon strate the contributions work as expected All tests MUST be triggered by the make check rule All test should have self verification to make sure the correct results are generated All tests MUST be activated by at least one of the integration tests of Jenkins the test jobs used to check if something can be merged into our central repository s master branch e This will ensure that no futu
113. ans bool isError NOT isNoError bool isFound NOT isNotFound Collections Plural form should be used on names representing a collection of objects This enhances readability since the name gives the user an immediate clue as to the type of the variable and the operations that can be performed on its elements For example vector lt Point gt points int values Constants Named constants including enumeration values MUST be all uppercase using underscore to separate words For example int MAX_ITERATIONS COLOR_RED double PI In general the use of such constants should be minimized In many cases implementing the value as a method is a better choice 99 Coding Standard int getMaxIterations NOT MAX_ITERATIONS 25 return 25 Generic Generic variables should have the same name as their type This reduces complexity by reducing the number of terms and names used Also makes it easy to deduce the type given a variable name only If for some reason this convention doesn t seem to fit it is a strong indication that the type name is badly chosen void setTopic Topic topic NOT void setTopic Topic value NOT void setTopic Topic aTopic NOT void setTopic Topic t void connect Database database NOT void connect Database db NOT void connect Database oracleDB Non generic variables have a role These variables can often be named by combining role and type Point
114. ar in the title page For works in formats which do not have any title page as such Title Page means the text near the most promi nent appearance of the work s title preceding the beginning of the body of the text The publisher means any person or entity that distributes copies of the Document to the public A section Entitled XYZ means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language Here XYZ stands for a specific section name mentioned below such as Acknowledgements Dedications En dorsements or History To Preserve the Title of such a section when you modify the Document means that it remains a section Entitled XYZ ac cording to this definition The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document These Warranty Dis claimers are considered to be included by reference in this License but only as regards disclaiming war ranties any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License 2 VERBATIM COPY ING You may copy and distribute the Document in any medium either commercially or noncommercially provided that this License the copyright notices and the license notice saying this License applies to the Document are reproduced in all copies and that you add no othe
115. arams LOC7 func 0 LOC8 gt L0C7 func 2 1 LOC9 gt L0C10 func 2 3 LOC11 gt L0C12 pending LOC10 LOC13 gt L0C14 gt LOC4 func 2 4 L0C15 gt L0C16 gt L0C17 func 2 5 LOC18 gt L0C14 gt L0C4 func 2 aliasPointer LOC19 gt L0C14 gt L0C4 func 2 pointer LOC20 gt L0C13 gt L0C14 gt L0C4 malloc LOC21 gt L0C22 inparams LOC2 gt outparams LOC12 printf LOC23 gt L0C24 inparams LOC16 gt L0C17 LOC14 gt L0C4 gt outparans LOC25 q dd4d4d4d444400 10 5 SSA ROSE has implemented an SSA form Some discussions on the mailing list link Rice branch has an implementation of array SSA We are waiting for their commits to be pushed into Jenkins Liao discuss e contribs 18 17 19 June 2012 UTC https mailman nersc gov pipermail rose public 2012 March 001496 html http en wikibooks org wiki User 3ALiao http en wikibooks org wiki User 20talk 3ALiao http en wikibooks org wiki Special 3AContributions 2FLiao NOD ow 45 Program Analysis 10 6 Side Effect Analysis Quick Facts e The algorithm is based on the paper K D Cooper and K Kennedy 1988 Interprocedural side effect analysis in linear time In Proceedings of the ACM SIGPLAN 1988 conference on Programming Language design and Implementation PLDI 88 R L Wexelblat Ed ACM New York NY USA 57 66 e Source Code src midend programAnalysis sideEffect Analysis e Tests tests roseTests programAnalysisTests sideEf
116. ard tracking for the translator it usually takes input and generate intermediate results before the final output is generated Using a debugger to set break points at each critical stages of the code to check if the intermediate results are what you expect backwards tracking similar to the previous techniques But you just back tracking the problem 20 10 3 Fix the bug Any bug fix commit should contain a regression test so make check rules can make sure the bug is actually fixed and no further code changes will make the bug relapse 20 11 How to add a ROSE commandline option 177 21 Lessons Learned Here we collect things to do due to some past lessons 21 1 Do Not Format Indent other people s code Lesson e A developer tried to understand a staff member s source code But he found that the code s indentation was not right for him So he re formatted the source files and committed the changes Later the staff member found that his code was changed too much and he could not read it anymore Solution e Please don t reformat code you do not own or will not maintain 21 2 Physical locations matter Lesson e we had a student who was assigned a desk which was in a deep corner of a big room The desk was also far away from other interns As a result that student had less interactions with others He had to solve problems with less help Solution e Locations MATTER Sit closer to people you should interact often Ma
117. arent and symbol table e Be careful to use deepDelete and deepCopy Some information might not be updated properly For example deepDelete might not update your symbol table 20 3 6 Verify the correctness You can use wholeAST graph to verify your translation All ROSE based translators should call Ast Tests run AllTests project after all the transformation is done to make sure the translated AST is correct This has a higher standard than just correctly unparsed to compilable code It is common for an AST to go through unparsing correctly but fail on the sanity check More information is at Sanity_ check 1 Chapter 8 1 on page 31 160 Sample translators 20 4 Sample translators Here we list a few sample translators which can grow to more sophisticated ones you want 20 4 1 Find pragmas toy code by Liao 12 14 2007 include rose h include lt iostream gt using namespace std class visitorTraversal public AstSimpleProcessing protected virtual void visit SgNode n 3 void visitorTraversal visit SgNode node if mode gt variantT V_SgPragmaDeclaration cout lt lt pragma lt lt endl F int main int argc char argv SgProject project frontend argc argv visitorTraversal myvisitor myvisitor traverselnputFiles project preorder return backend project 20 5 How to build your translator See How to set up the makefile for a trans
118. ary calls Binary Analysis e BinaryCloneDetection detect similarities between binary executables e CloneDetection Optimizations of high level abstractions e arrayOptimization optimizations based on array abstractions autoParallelization A translator which can automatically insert OpenMP directives into serial code based on dependence analysis and optionally semantics of abstractions Parallel Programming Models e mint a directive based programming model for GPUs e OpenMP_ Translator the first version of OpenMP implementation using ROSE Not recommended for production use kept just as an example e UpcTranslation a preliminarily example project to demonstrate how ROSE can be used to created a UPC compiler 81 ROSE Projects 13 1 minitermite Problem A student added some new IR nodes into ROSE She is having trouble to pass make for minitermite Solution projects minitermite HOWTO_ ADD NEW_SGNODE_VARIANTS 82 14 Developer s Guide We briefly describe the workflow of ROSE developers 14 1 Basic skills for ROSE developers These are some basic skills that ROSE developers should have or acquire e Shell programming Bash Bourne Again Shell is the default shell for ROSE e Unix commands grep find ssh etc e C programming be conscious of applying consistent coding style conventions and writing code that will be maintainable when you leave e Debugging GDB will be invaluable to make sure your
119. as you received it does not specify a version number of the GNU Lesser Gen eral Public License you may choose any version of the GNU Lesser General Public License ever pub lished by the Free Software Foundation If the Library as you received it specifies that a proxy can decide whether future versions of the GNU Lesser General Public License shall apply that proxy s public statement of acceptance of any version is permanent authorization for you to choose that version for the Library
120. ated Any commits from a developer s private repository will not be immediately merged to the master branch of the shared repository In fact we have access control to prevent any developer from pushing commits to the master branch within the shared repository A continuous integration server called Jenkins is actively monitoring each developer s branch within the central repository and will initiate comprehensive commit tests upon the branch once new commits are detected Finally Jenkins will merge the new commits to the master branch of the central repository if all tests pass If a single test fails Jenkins will report the error and the responsible developer should address the error in his private repository and push improved commits again As a result the master branch of the central git repository is mostly stable and can be a good candidate for our external release On top of the master branch of the central git repository we further have more comprehensive release tests in Jenkins If all the release tests pass an external release based on the master branch will be made available outside 18 3 Tests on Jenkins We use Jenkins http hudson rose 30 8080 to test commits added to developer s release candidate branches at the central git repository The tests are organized into three categories 1 http en wikipedia org wiki Continuous 20integration 128 Installed Software Packages e Integration tests used to ch
121. ay change the nodes the traversal is expected to visit later on Conceptually this is essentially a similar problem to C iterator invalidation To safely transform AST It is recommended to use a reverse iterator of the statement list generated by a preorder traversal This is different from a list generated from a post order traversal For example assuming we have a subtree of parent lt child 1 child 2 gt e Pre order traversal will generate a list parent child 1 child2 e Post order traversal will generate a list child 1 child2 parent e Reverse iterator of the pre order will give you child2 child 1 and parent Transforming using this order is the safest based on our experiences 9 6 Example translators There are many test translators under https github com rose compiler rose tree master tests roseTests astInterfaceTests e buildForStmt C e buildFunctionCalls C e buildPragmaDeclaration C e and so on Other examples 1 Chapter 20 3 on page 158 36 Trouble shooting e Split one complex statement into multiple simpler statements ROSE projects back stroke ExtractFunctionArguments C 9 7 Trouble shooting 9 7 1 Assertion failed expr gt get_startOfConstruct NULL Assertion failed expr gt get_startOfConstruct NULL function unparseExpression file ROSE src backend unparser languagelndependenceSupport unparseLanguagelndependentConstructs line 812 void visitorTraversa
122. blem for editors printers terminal emulators or debuggers when used in a multi programmer multi platform environment We already have a built in perl script to enforce this policy 16 8 5 Header Files File name e must be camelCase such as fileName h or fileName hpp e avoid file name h Suffix e For C header files Use h e For C header files Use h or hpp Must have e protected preprocesssing directives to prevent the header from being included more than once example ifndef _HEADER_FILE_X_H_ define _HEADER_FILE_X_H_ endif _HEADER_FILE_X_H_ e try to put your variables functions classes within a descriptive namespace e Include statements must be located at the top of a file only e Avoid unwanted compilation side effects by hidden include statements deep into a source file What to avoid e global variables functions or classes they will pollute the global scope using namespace std 104 README e this will pollute the global scope for each cpp file which includes this header using namespace should only be used by cpp files More explanations are at link and link2 e function definitions References e http www parashift com c faq hdr file ext html 16 8 6 Source Files Again file names should follow the name convention e camelCase file name e g sagelnterface cpp e Avoid capitalization spaces special characters Preferred suffix e Use c for C source files
123. bool hasLicense e bool canEvaluate e bool shouldSort Parameters should be separated by a single space character with no leading or trailing spaces in the parameters list e YES void foo int x int y e NO void foo int x int y 16 7 Directories 16 7 1 Naming Convention List of common names e src to put source files headers e include to put headers if you have many headers and don t want to put them all into sre e tests put test inputs e docs detailed documentation not covered by README Please use camelCase for your directory name e you should avoid leading Capitalization Examples of preferred names e roseExtensions e roseSupport e roseAPI What to avoid e rose_api e rose_support 16 7 2 Layout TODO big picture about where to put things within the ROSE git repository For each project directory under projects it is our convention to have subdirectories for different files e README must have this e src for all your source files e include for all your headers if you don t want to put them all into sre e tests for your test input files 102 Files e doc for your more extensive documentation if README is not enough 16 8 Files A single file should contain one logical unit or feature Keep it modular 16 8 1 Naming Conventions A file name should be specific and descriptive about what it contains You should use camelCase lowercase character in the beginning
124. bose 0 edg restrict I ROSE tests CompileTests virtualCFG_tests Cxx_tests I sourcetree tests CompileTests A Code c 168 How to debug a translator ROSE tests CompileTests virtualCFG_tests Cxx_tests test2001_01 C warning no loadable sections found in added symbol file system supplied DSO at Ox2aaaaaaab000 Thread debugging using libthread_db enabled 1t testVirtualCFG ROSE src frontend SageIII virtualCFG virtualCFG h 111 VirtualCFG CFGEdge CFGEdge VirtualCFG CFGNode VirtualCFG CFGNode Assertion src getNode tgt getNode __null failed _null amp amp Program received signal SIGABRT Aborted 0x0000003752230285 in raise from 1ib64 libc so 6 Okay we ve reproduced the problem in our GDB session 4 Let s check the backtrace to see how we wound up at this failed assertion gdb bt 0 0x0000003752230285 in raise from 1ib64 libc so 6 1 0x0000003752231d30 in abort from 1ib64 libc so 6 2 0x0000003752229706 in __assert_fail from 1ib64 libc so 6 3 0x00002aaaad6437b2 in VirtualCFG CFGEdge CFGEdge this 0x7fffffffb300 src tgt at ROSE src frontend SageIII virtualCFG virtualCFG h 111 4 0x00002aaaad643b60 in makeEdge lt VirtualCFG CFGNode VirtualCFG CFGEdge gt from to result at ROSE src frontend SageIII virtualCFG memberFunctions C 82 5 0x00002aaaad62ef7d in SgReturnStmt cfgOutEdges this 0xbfaf10
125. bution You may click on the image numbers in the following table to open the webpage of the images in your webbrower 10 Chapter 31 on page 217 214 List of Figures 1 Peihunglin cc by sa 3 0 2 Chunhualiao cc by sa 3 0 3 Chunhualiao cc by sa 3 0 4 Liao cc by sa 3 0 5 Chunhualiao cc by sa 3 0 6 Peihunglin cc by sa 3 0 7 Peihunglin cc by sa 3 0 11 http en wikibooks org wiki User 3APeihunglin 12 http en wikibooks org wiki User 3AChunhualiao 13 http en wikibooks org wiki User 3AChunhualiao 14 http en wikibooks org wiki User 3ALiao 15 http en wikibooks org wiki User 3AChunhualiao 16 http en wikibooks org wiki User 3APeihunglin 17 http en wikibooks org wiki User 3APeihunglin 215 31 Licenses 31 1 GNU GENERAL PUBLIC LICENSE Version 3 29 June 2007 Copyright 2007 Free Software Foundation Inc lt http fsf org gt Everyone is permitted to copy and distribute verba tim copies of this license document but changing it is not allowed Preamble The GNU General Public License is a free copyleft license for software and other kinds of works The licenses for most software and other practi cal works are designed to take away your freedom to share and change the works By contrast the GNU General Public License is intended to guaran tee your freedom to share and change all versions of a program to make sure it remains free software for
126. c is being assigned to 170 How to add a new project directory Breakpoint 1 SgReturnStmt cfgDutEdges this 0xbfaf10 idx 1 at ROSE src frontend SageIII virtualCFG memberFunctions C 1472 1472 SgFunctionDefinition enclosingFunc SageInterface getEnclosingProcedure this So this is the line we re examining SgFunctionDefinition enclosingFunc SageInterface getEnclosingProcedure this So the NULL value must be coming from SageInterface getEnclosingProcedure this After code reviewing the function getEnclosingProcedure we discovered a flaw in the algorithm The function tries to return a SgNode which is the enclosing procedure of the specified type SgFunctionDefinition However upon checking the function s state at the point of return we see that it incorrectly detected a SgBasicBlack as the enclosing procedure for the SgReturnStmt gdb p parent gt class_name 12 static npos 18446744073709551615 _M_dataplus lt std allocator lt char gt gt lt __gnu_cxx new_allocator lt char gt gt lt No data fields gt lt No data fields gt _M_p Ox7cd0e8 SgBasicBlock Specifically the last piece 0x7cd0e8 SgBasicBlock But this is wrong because we re looking for SgFunctionDefinition not SgBasicBlock Upon further examination we figured out that the function simply returned the first enclosing node it found and not the first enclosing node that matched the user s criteria
127. canned to generate the web reference html files make doxygen_docs C ROSE_BUILD docs Rose 16 10 2 Use TODO This is a recommended way to improve your code s comments While doing incremental development it is often to have something you decide to do in the next iterations or you know your current implementation functions have some limitations to be fixed in the future A good way is to immediately put a TODO source comments TODO blar blar into the relevant code when you make such kind of decisions so you won t forget here is something you want to do next time The TODOs also serve as some handy flags within the code for other people if they want to improve your work after you are gone 16 10 3 Examples Single Line Often a brief single line comment is enough Brief description 107 Coding Standard Multiple lines Doxygen supports comments with multiple lines KK Bent KK E nd LOL il e text FAC ACCA ACA AC ACK AA AA AAA AA AA IIILLILLILLLLLIILLLIL ILLI AA ASIS teat lt 80 columns in length IIILLIILIILLLLIILLLLL IILL II Combined single line and multiple lines Doxygen can generate a brief comment for a function and optionally show detailed comments if users click on the function Here are the options to support combined single line and multiple line source comments Option 1 JK brief Brief description Brief description continued Se
128. ce and time complexity Implementation Does the implementation correctly implement the documented algo rithms e Testing Does the code has the accompanying test translator and input to ensure the contributions do what they are supposed to do e Is Jenkins being configured to trigger these tests Local tests on developer s workstation do not count 16 1 2 Avoid Coding Standard War We directly quote text from http www parashift com c faqg coding std wars html as follows 1 Chapter 17 on page 115 91 Coding Standard Nearly every software engineer has at some point been exploited by someone who used coding standards as a power play Dogmatism over minutia is the purvue of the intellectu ally weak Don t be like them These are those who can t contribute in any meaningful way who can t actually improve the value of the software product so instead of exposing their incompetence through silence they blather with zeal about nits They can t add value in the substance of the software so they argue over form Just because they do that doesn t mean coding standards are bad however Another emotional reaction against coding standards is caused by coding standards set by individuals with obsolete skills For example someone might set today s standards based on what programming was like N decades ago when the standards setter was writing code Such impositions generate an attitude of mistrust for coding standards As abo
129. ceFile SgFile fileNode isSgFile n translateFileName fileNode F break case V_SgProgramHeaderStatement break default break More information about AST Traversal can be found at 7 AST Traversal of the ROSE User manual pdf online 159 How tos 20 3 5 Performing Translation The translations you want to do often depend on the types of the AST nodes you visit For example you can have a set of translation functions defined in your namespace e void translateForLoop SgForLoop n e void translateFileName SgFile n e void translateReturnStatement SgReturnStmt n and so on Other tips e Reference ROSE doxygen website for information of each AST node http rosecompiler org ROSE_HTML_Reference index html e Use SageBuilder namespace http rosecompiler org ROSE_HTML_Reference namespaceSageBuilder html if you want to create new AST node Update SageBuilder you cannot find the one you need e Look up in Sagelnterface Namespace http rosecompiler org ROSE_HTML_ Reference namespaceSagelnterface html for the translation functions you need If there is none then write your own function e Besides building things from scratch you can use Sagelnterface deepCopy to copy AST subtree e Update the information or create the new AST node you need e Replace the existing AST node with your updated or new AST node Updating Tree e You might need to handle some details like removing symbol updating p
130. ces to the extent that it includes a con venient and prominently visible feature that 1 dis plays an appropriate copyright notice and 2 tells the user that there is no warranty for the work ex cept to the extent that warranties are provided that licensees may convey the work under this Li cense and how to view a copy of this License If the interface presents a list of user commands or options such as a menu a prominent item in the list meets this criterion 1 Source Code The source code for a work means the preferred form of the work for making modifications to it Object code means any non source form of a work A Standard Interface means an interface that ei ther is an official standard defined by a recognized standards body or in the case of interfaces spec ified for a particular programming language one that is widely used among developers working in that language The System Libraries of an executable work in clude anything other than the work as a whole that a is included in the normal form of packag ing a Major Component but which is not part of that Major Component and b serves only to en able use of the work with that Major Component or to implement a Standard Interface for which an implementation is available to the public in source code form A Major Component in this context means a major essential component kernel window system and so on of the specific o
131. code works as expected e Git Source code management SCM get familiar with the basics of Git http git scm com e Build systems GNU Autotools autoconf automake GNU Make GNU libtool e CMake primarily so you won t break our existing Windows port e LaTex Document your work in ROSE docs e ROSE Documentation Be familiar with ROSE documents tutorials installation and developer guides http rosecompiler org documents html This also includes the project s Doxygen documentation e Compilers ROSE is a compiler project after all Take some compiler courses Read free online course materials related to compilers e Keep learning topics related to your projects References e http www mediawiki org wiki Git Tutorial very good Git Tutorial e http eagain net articles git for computer scientists 14 2 Valued Contributions The ROSE project values the following contributions Development e Code implementing new compiler features improving existing work passing code review and Jenkins Only commits which were merged into the central master branch count as contributions e Parsing for language support e AST e analysis 83 Developer s Guide e optimizations e build system e Bug fixes passing code review and Jenkins in the future Klocwork Coverity etc analysis tools e reported by users on SciDAC outreach center s bug tracker e found by ourselves reported on github com or redmine e Documentation wr
132. collaboration 2 AsciiDoc 206 29 Sandbox Some common tricks to write things on wikibooks wikipedia both are using the mediawiki software 29 1 How to create a new page Usually you have to start a new page from an existing wikipage Go to the wiki page you want to have a link to the new page you want to create e click the edit tab the existing page e at the place you want to have a link to the new page use ROSE_Compiler_Framework name of the pagel e If there is already a page with the desired name It will become a link to the page e If not the link is red so you can click the red link to enter editing model to add content to the page Please link the new page to the print version of this wikibook so it can be visible in the print out e To edit the print version go to http en wikibooks org w index php title ROSE_ Compiler_Framework Print_version amp action edit 29 2 How to do XYZ in wiki The best way is to goto en wikipedia com and find a page with the output you want Then pretend to edit the page by clicking edit to see the source used to generate the output For example you want to know how C syntax highlighting is obtained in wikibook Go to en wikipedia com and find the page for C There must be sample code snippet Then you pretend to edit it to see the source http en wikipedia org w index php title C 2B 2Bkaction edit amp section 6 You will see the source code generating the syntax highligh
133. covered work These actions infringe copyright if you do not accept this License Therefore by mod ifying or propagating a covered work you indicate your acceptance of this License to do so 10 Auto matic Licensing of Downstream Recipients Each time you convey a covered work the recipient automatically receives a license from the original licensors to run modify and propagate that work subject to this License You are not responsible for enforcing compliance by third parties with this License An entity transaction is a transaction transfer ring control of an organization or substantially all assets of one or subdividing an organization or merging organizations If propagation of a cov ered work results from an entity transaction each party to that transaction who receives a copy of the work also receives whatever licenses to the work the party s predecessor in interest had or could give un der the previous paragraph plus a right to posses sion of the Corresponding Source of the work from the predecessor in interest if the predecessor has it or can get it with reasonable efforts You may not impose any further restrictions on the exercise of the rights granted or affirmed under this License For example you may not impose a license fee royalty or other charge for exercise of rights granted under this License and you may not ini tiate litigation including a cross claim or counter claim in a lawsuit alleging
134. ctual assumptions of lia bility to the recipient for any liability that these contractual assumptions directly impose on those licensors and authors All other non permissive additional terms are con sidered further restrictions within the meaning of section 10 If the Program as you received it or any part of it contains a notice stating that it is gov erned by this License along with a term that is a further restriction you may remove that term If a license document contains a further restriction but permits relicensing or conveying under this License you may add to a covered work material governed by the terms of that license document provided that the further restriction does not survive such relicensing or conveying If you add terms to a covered work in accord with this section you must place in the relevant source files a statement of the additional terms that ap ply to those files or a notice indicating where to find the applicable terms Additional terms permissive or non permissive may be stated in the form of a separately written license or stated as exceptions the above require ments apply either way 8 Termination You may not propagate or modify a covered work except as expressly provided under this License Any attempt otherwise to propagate or modify it is void and will automatically terminate your rights under this License including any patent licenses granted under the third paragraph of s
135. d gt 3 1 2 Public repo e Public Repositories Obtaining ROSE e Public git repository hosted at https github com rose compiler rose the con tent is identical to the private git repository at LLNL except that the proprietary EDG submodule is not released e Downloadable packages and a subversion repository synchronized with stable snap shots of ROSE s git repository https outreach scidac gov projects rose 3 2 Virtual Machine Image It can take quite some time to install ROSE for the first time A virtual machine image is provided with a Ubuntu 10 04 OS with ROSE already installed You can download it and play it using VMware Player 3 2 1 Downloading The Virtual Machine Image e http www rosecompiler org Ubuntu ROSE Demo tar gz e Demonstration user account sudo user in Ubuntu e account demo e password password e Warning The file is quite large at 4 8 GB More information is at ROSE Virtual Machine Image 3 3 git 1 7 10 or later for github com github requires git 1 7 10 or later to avoid https cloning errors as mentioned at https help github com articles https cloning errors Ubuntu 10 04 s package repository contains git 1 7 0 4 So building later version of git is needed But you still need an older version of git to get the latest version of git apt get install git core Now you can clone the latest git git clone https github com git git git Install all prerequis
136. d the use of http www 7 zip org The ATEX source itself was generated by a program written by Dirk H nniger which is freely available under an open source license from http de wikibooks org wiki Benutzer Dirk_Huenniger wb2pdf This distribution also contains a configured version of the pdflatex compiler with all necessary packages and fonts needed to compile the ATEX source included in this PDF file Contents 1 About the Book 1 1 1 2 1 3 1 4 Goal How To Contribute s s o s ee ee we ee ee a Tracking Wiki Changes 2 Co Coon nn Wikibook Writing Tips 2 22 2 Coon nn 2 ROSE s Documentations 3 Obtaining ROSE Git Repositories ur AY Gone BE Rae eae Se BE Sey ES Virtual Machine Image 2 2 Con nn git 1 7 10 or later for github com 2 220 4 EDG source code aoaaa EDG tarball tno na 2 28 2 da et A ae a os a pai a 3 1 3 2 3 3 3 4 3 5 4 Installation Platform Requirement sea 3 kanal aaa VR p ea k Software Requirement 2 2 22 Cm 4 1 4 2 4 3 4 4 4 5 4 6 4 7 4 8 4 9 4 10 build CONN UTE soe ae eh GA Oke blah Dae Bullen Gene make make cheek a 2 4 tun ee Be Be Bo eB a ene he Se BR SS make install 2 ac te en ee BO lee Bell OE o en set environment variables ee try out arose translator nn Trotibl shoting ota an eh ead ma Beni 5 Virtual machine image 5 1 5 2 5 3 6 ROSE tools 6 1 6 2 6 3 6 4 6 5 6 6 How to use
137. db p tgt getNode 2 SgNode 0x0 Ah there s the culprit So for some reason tgt getNode is returning a null SgNode pointer 0x0 From here we used the GDB up command to backtrace in the program to figure out where the node returned by tgt getNode was assigned a NULL value We eventually found a call to SgReturnStmt cfgOutEdges which returns a variable called enclosingFunc In the source code there s currently no assertion to check the value of enclosingFunc and that s why we received the assertion later on in the program As a side note it is good practice to add assertions as soon as possible in your source code so in times like this we don t have to spend time unnecessarily back tracing After adding the assertion for enclosingFunc we run the program again to reach this new assertion point lt testVirtualCFG RO SE sourcetree src frontend SagellI virtualCFG memberFunctions C 1473 virtual std vector lt VirtualCFG CFGEdge std allocator lt VirtualCFG CFGEdge gt gt SgReturnStmt cfgOutEdges unsigned int Assertion enclosingFunc __null failed Okay it s failing so we know that the assignment to enclosingFunc is NULL enclosingFunc is definitely NULL 0x0 gdb p enclosingFunc 1 SgFunctionDefinition 0x0 What is the current context gdb p this 2 SgReturnStmt const Oxbfaf10 Okay we re inside of an SgReturnStmt object Let s set a break point where enclosingFun
138. dd new versions as new slides linkt 4 https docs google com presentation d 1US3e9sXn j PvgRU9cy0f QgKZBHScGiCMODSsbQH80i8s edit 132 19 Frequently Asked Questions FAQ We collect a list of frequently asked questions about ROSE mostly from the rose public mailing list link 19 1 General 19 1 1 How to search rose public mailinglist for previously asked questions google com supports search things within the scope of a URL For example if you have a problem with a keyword MY PROBLEM you can try to search the mailing list by using the following keyword in google com MY PROBLEM site https mailman nersc gov pipermail rose public 19 1 2 Why can t ROSE staff members answer all my questions It can feel very frustrating when you get no responses to your questions submitted to the rose public nersc gov mailing list You may wonder why the ROSE staff cannot help neither sometimes Here are some possible excuses e They are just as busy as everybody else in the research and development fields They may be working around the clock to meet deadlines for proposals papers project reviews deliverables etc e They don t know every corner of their own compiler given the breadth and depth of contributions made to ROSE by collaborators former staff members post docs and interns Moreover most contributions lack good documentation something that should be remedied in the future e Some questions are simply
139. de review and continuous integration e Iterative and Incremental software development for early results controllable risks and better engagement of stakeholders e Code review for consistency maintainability usability and quality e Continuous Integration for automated testing easy release and scalable collaboration 15 2 1 Incremental Development Developing new functionality in small steps where the resulting code at each step is a useful improvement over the previous state Contrast to developing an entire feature fully elaborated with no points along the way at which it s externally usable Each ROSE developer is expected to push his her work at least once every three weeks Major benefits of doing things incrementally e You can have intermediate results along the path So your sponsors will sleep better e You will get feedback early and frequently about if you are heading to the right direction e Your work will be tested and merged often into the master branch avoiding the risks of merge conflicts See more tips about How to incrementally work on a project 1 Chapter 20 2 on page 157 87 Workflow 15 2 2 Code Review See Code Review in ROSE 15 2 3 Continuous Integration Incorporating changes from work in progress into a shared mainline as frequently as possible in order to identify incompatible changes and introduced bugs as early as possible The integrated changes need not be particular increments o
140. der the terms of sections 4 and 5 provided that you also convey the machine readable Correspond ing Source under the terms of this License in one of these ways a Convey the object code in or embodied in a physical product including a physical distribu tion medium accompanied by the Corresponding Source fixed on a durable physical medium custom arily used for software interchange b Convey the object code in or embodied in a physical product including a physical distribution medium accom panied by a written offer valid for at least three years and valid for as long as you offer spare parts or customer support for that product model to give anyone who possesses the object code either 1 a copy of the Corresponding Source for all the software in the product that is covered by this Li cense on a durable physical medium customarily used for software interchange for a price no more than your reasonable cost of physically performing this conveying of source or 2 access to copy the Corresponding Source from a network server at no charge c Convey individual copies of the object code with a copy of the written offer to provide the Corresponding Source This alternative is al lowed only occasionally and noncommercially and only if you received the object code with such an of fer in accord with subsection 6b d Convey the object code by offering access from a designated place gratis or for a charge and offer equ
141. developers by examples Examples should be concise and to the point e On the other hand translators used to build end user tools should have much higher standard to accept command options for different even advanced features These translators can be very sophisticated since they don t have the page limitation as tutorial examples do 28 7 Supported Programming Languages ROSE supports a wide range of main stream programming languages with different degrees of maturity The list of supported languages includes e Cand C based on the EDG C frontend version 3 3 e An ongoing effort is to upgrade the EDG frontend to its recent 4 4 version e Another ongoing effort is to use clang as an alternative open source C C frontend e Fortran 77 95 2003 based on the Open Fortran Parser e OpenMP 3 0 based on ROSE s own parsing and translation support for both C C and Fortran OpenMP programs e UPC 1 1 this is also based on the EDG 3 3 frontend 7 1 OpenMP ROSE supports OpenMP 3 0 for C C and limited Fortran support e The ROSE manual has a chapter Chapter 12 OpenMP Support explaining the details pdf e A paper was published for the uniqueness of the ROSE OpenMP Implementation pdf e Frontend parsing source files ompparser yy and ompFortranParser C are located under https github com rose compiler rose tree master src frontend Sagelll e The transformation of OpenMP into threaded code is located in omp_ lowering cpp under
142. e lt lt lt lt nextN getNode gt unparseToString lt lt gt lt lt visited lt lt visited find nextN visited end lt lt remaining lt lt isRemaining nextN lt lt n if we haven t yet visited this node and don t yet have it on the remainingNodes list if visited find nextN visited end amp amp lisRemaining nextN printf pushing back node lt s 0Ox x s gt visited d n nextN getNode gt class_name c_str nextN getNode nextN getNode gt unparseToString c_str visited find nextN visited end remainingNodes push_back nextN if we still have any nodes left remaining 64 Analysis Driver if remainingNodes size gt 0 take the next node from the front of the list and mark it as visited visited remainingNodes front true visited insert remainingNodes front class dataflow public virtual iterator class back_dataflow public virtual dataflow void back_dataflow operator int advance false true backward add all children class IntraUniDirectionalDataflow public IntraUnitDataflow dE virtual VirtualCFG dataflow getInitialWorklist const Function amp func bool firstVisit bool analyzeDueToCallers const set lt Function gt amp calleesUpdated NodeState fState 0 F Implemented in derived classes e VirtualCFG dataflow IntraFW Dataflow getInitialWorklist e Virtua
143. e identity Translator help to see all options e debug a ROSE based translator the first step is often to use identity Translator to rule out if it is a compilation problem using ROSE e use the source of the identityTranslator as a start point to add custom analysis and transformation The code in the identityTranslator is indeed the minimum code required for almost all kinds of ROSE based tools 6 2 2 Source code identity Translator c include rose h int main int argc char argv Build the AST used by ROSE SgProject project frontend argc argv Run internal consistency tests on AST AstTests runAllTests project Insert your own manipulation of the AST here Generate source code from AST and call the vendor s compiler return backend project 6 2 3 Limitations But due to limitations of the frontends and the internal processing it cannot generate 100 identical output compared to the input file Some notable changes it may introduce include e int a b c are transformed to three SgVariableDeclaration statements e macros are expanded e extra brackets are added around constants of typedef types e is translated in the output to c Typedef_Example 12 e Converting NULL to 0 g c Typedef_Example 12 6 3 AST dot graph generators Tools to generate AST graph in dot format There are two versions e dotGenerator simple AST graph generator showing essential nodes and edges e
144. e initializeFunctionNodeState const Function amp func NodeState fState VirtualCFG dataflow getInitialWorklist const Function amp func bool firstVisit bool analyzeDueToCallers const set lt Function gt amp calleesUpdated NodeState fState virtual vector lt Lattice gt getLatticeAnte NodeState state virtual vector lt Lattice gt getLatticePost NodeState state void transferFunctionCall const Function amp func const DataflowNode amp n NodeState state vector lt DataflowNode gt getDescendants const DataflowNode amp n next CFG nodes depending on the direction return gatherDescendants n inEdges amp DataflowEdge source DataflowNode getUltimate const Function amp func the last CFG should be the start CFG of the function for a backward dataflow problem return cfgUtils getFuncStartCFG func get_definition 61 Generic Dataflow Framework foward intra procedural data flow analysis e g reaching definition e class IntraFWDataflow public IntraUniDirectionalDataflow 11 7 2 Initialization InitDataflowState Used to initialized the lattices facts for CFG nodes It is an analysis by itself unstructured pass super class provides the driver of initialization visit each CFG node class UnstructuredPassIntraAnalysis virtual public IntraProceduralAnalysis public call the initialization function on each CFG node bool runAnalysis const Function amp func
145. e integrated into ROSE s official master branch 6 Setup polling job Contact the Jenkins administrator tool and liao6 to have your Github repository polled for new changes on the master branch When new changes are detected your master branch will be pushed to the central repository and added to the Jenkins testing queue as lt oun gt reviewd rc 17 4 3 Daily work process e have a local git repo to do your work and submit local commits you have two choices e clone it from nfs casc overture rose rose git as we usually do before e clone your fork on github linl gov to a local repo only HTTPS is supported via LC Note You may encounter SSL certificate problems If you do simply disable SSL verification in cURL using either export GIT_SSL_NO _VERIFY false or configuring git git config global http sslVerify false e e don t use branches use separated git repositories for each of your tasks So sta tus progress of one task won t interfere with other tasks e When ready to push your commits synchronize with the latest rose compiler master to resolve merge conflicts etc e type git pull origin master this should always work since master branches on github llnl gov are automatically kept up to date e make sure your local changes can pass 1 make j8 2 make check j8 and 3 make distcheck j8 e push your commits to your fork s non master branch like bugfix re featurex rc work status etc You have total freedom in creati
146. e Author information who participates in the major writing e Reviewer information who reviews and approves the document e Table of contents e Page numbering format e Section numbers e Revision history 16 3 5 Content Major Sections e Overview e Explain the motivation and goal of the module what does this module do the goal the problem to address etc e Requirement analysis what is required for this module e Define the interface namespace function names parameters return values How others can call this module and obtain the returned results e Performance requirement time and space complexity e Scope of input test codes what types of languages to be supported the constructs of a language to be supported the benchmarks to be used e Design considerations e Assumptions e Constraints e Tradeoffs and limitations why this algorithm what are the priorities etc e Non standard elements Definitions of any non standard symbols shapes acronyms and unique terms in the document e Game plan How each requirement will be achieved e Internal software workflow e Diagrams logical structure and logical processing steps MUST have a UML diagram or power point diagram e Pseudo code MUST have pseudo code to describe key data structures and high level algorithm steps e Example Must illustrate the designed algorithm by using at least one sample input code to go through the important intermediate results of the algorithm e Error alarm
147. e don t use level one or level two headings in a how to page Keep each how to short and focused Readers are expected to only spend 30 minutes or much less to quickly learn how to do something using ROSE After you created a new how to page and saved your contributions Please go to the print version to make sure it shows up correctly e Here is the link http en wikibooks org wiki ROSE_Compiler_Framework Print_version e Having new content show up in the print version will make sure it is really visible and consistent with the rest of the book please specify the how to topic is the current practice or the proposed new ways of doing things So we can have clear guideline for code review for what is mandatory and what is optional 20 2 How to incrementally work on a project Developing a big sophisticated project entails many challenges To mitigate some of these challenges we have adopted several best practices incremental development code review and continuous integration Here are some tips on how to divide up a big project into smaller bite sized pieces so each piece can be incrementally developed code reviewed and integrated Input define different sets of test inputs based on complexity and difficulty Tackle simpler sets first Output define intermediate results leading to the final output Often results A and B are needed to generate C So the project can have multiple stages based on the intermediate res
148. e features including e Distributed source code management Developers can have a self contained local repository to do their work anywhere they want without the need for active connection to a central repository e Easy merge Merging using Git is as simple as it can get e Backup Since easy clone of our central repository can serve as a standalone repository We no longer worry too much about losing the central repository e Integrity Hashing algorithm used by Git ensures that you will get out what you have put into the repository Many other prominent software projects have also been through the similar switch from Subversion to Git including e the Linux kernel e Perl e Eclipse e Gnome e KDE e Android e Debian e MediaWiki e http gcc gnu org git e http darcs haskell org ghc git A more comprehensive list of Git users is given by https git wiki kernel org index php GitProjects In summary Git IS the state of the art for source code management 23 2 git 1 7 10 or later for github com github requires git 1 7 10 or later to avoid HTTPS cloning errors as mentioned at https help github com articles https cloning errors 185 Git Ubuntu 10 04 s package repository has git 1 7 0 4 So building later version of git is needed But you still need an older version of git to get the latest version of git apt get install git core Now you can clone the latest git git clone https
149. e near the top of the Makefile am e SUBDIRS This variable should contain the names all the project s subdirectories that have Makefiles It may be omitted if the project s only Makefile is in that project s top level directory e INCLUDES This would have the the flags that need to be added during compilation flags like I top_srcdir projects RTC include Your flags should be placed before ROSE_INCLUDES to ensure the correct files are found This brings in all the necessary headers from the src directory to your project e lib_ These variables targets are necessary if you are creating a library from your project which can be linked in with other projects or the src directory later This is the recommended way of handling projects e EXTRA_DIST These are the files that are not listed as being needed to build the final object like source and header files but must still be in the ROSE tarball distribution This could include README or configuration files for example e check local This is the target that will be called from the higher level Makefiles when make check is called e clean local Provides you with a step to perform manual cleanup of your project for instance if you manually created some files so Automake won t automatically clean them up 20 9 4 A basic example Many projects start as a translator analyzer or optimizer which takes into input code and generate output A basic sample commit which adds a new project
150. e tests roseTests programAna lysisTests generalDataFlowAnalysisTests liveDeadVarAnalysisTest C 101 11 6 Control flow graph and call graph The generic dataflow framework works on virtual control flow graph in ROSE 11 6 1 Filtered Virtual CFG The raw virtual CFG may not be desirable for all kinds of analyses since it can have too many administrative nodes which are not relevant to a problem So the framework provides a filter parameter to the Analysis class A default filter will be used unless you specify your own filter 58 Analysis Driver Example filter funtion deciding if a CFGnNode should show up or not bool gfilter CFGNode cfgn SgNode node cfgn getNode switch node gt variantT Keep the last index for initialized names This way the def of the variable doesn t propagate to its assign initializer case V_SgInitializedName return cfgn node gt cfgForEnd For function calls we only keep the last node The function is actually called after all its parameters are evaluated case V_SgFunctionCallExp return cfgn node gt cfgForEnd For basic blocks and other container nodes keep the node that appears before the contents are executed case V_SgBasicBlock case V_SgExprStatement case V_SgComma0pExp return cfgn node gt cfgForBeginning Must have a default case return interesting CFGNode by default in this example default return cfgn isInteresting
151. eVarsLattice class LiveVarsLattice public FiniteLattice public std set lt varID gt liveVars bottom is all live variables top is the empty set meet brings down the lattice gt union of 54 Transfer Function variables Meet operation simplest set union of two lattices computes the meet of this and that and saves the result in this returns true if this causes this to change and false otherwise bool LiveVarsLattice meetUpdate Lattice that_arg bool modified false LiveVarsLattice that dynamic_cast lt LiveVarsLattice gt that_arg Add all variables from that to this for set lt varID gt iterator var that gt liveVars begin var that gt liveVars end var I this lattice doesn t yet record var as being live if liveVars find var liveVars end this if statement gives a chance to set the modified flag otherwise liveVars insert can be directly called modified true liveVars insert var return modified 11 5 Transfer Function basics Data_flow_analysis flow 2Ftransfer_ function e IN sum of OUT predecessors OUT GEN IN KILL The impact of program constructs on the current lattices how to change the current lattices e lattices stores IN and OUT information e additional data members are necessary to store GEN and KILL set inside the transfer function class hierarchy class IntraDFTransferVisitor public ROS
152. eck if the new commits can pass various make check rules compatibility tests portability tests configuration tests and so on If all tests pass the commits will be merged or integrated into the master branch of the central repository e Release tests used to test the updated master branch of the central repository for additional set of tests using external benchmarks If all tests pass the head of the master will be released as a stable snapshot for public file package releases generated by make dist e Others for informational purpose now not being used in our production workflow So for each push one or more commits to a rc branch it will go through two stages Integration test and Release test stage It is each developer s responsibility to make sure their commits can pass BOTH stage by fixing any bugs discovered by the tests 18 4 Installed Software Packages Here we list software packages installed and used by Jenkins e Yices export tmp hudson rose opt yices 1 0 34 18 5 Check Testing Results It is possible to manually tracking down how you commits are doing within the test pipeline within Jenkins http hudson rose 30 8080 But it can be tedious and overwhelming So we provide a dashboard http sealavender 4000 to summarize the commits to your release candidate branch rc and the pass fail status for each integration tests Note It s possible that all of your testing jobs finally pass but the act
153. ection 11 However if you cease all violation of this License then your license from a particular copyright holder is reinstated a provisionally unless and until the copyright holder explicitly and finally terminates your license and b permanently if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessa tion Moreover your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reason able means this is the first time you have received notice of violation of this License for any work from that copyright holder and you cure the vi olation prior to 30 days after your receipt of the notice Termination of your rights under this section does not terminate the licenses of parties who have re ceived copies or rights from you under this License If your rights have been terminated and not perma nently reinstated you do not qualify to receive new licenses for the same material under section 10 9 Acceptance Not Required for Having Copies You are not required to accept this License in or der to receive or run a copy of the Program Ancil lary propagation of a covered work occurring solely as a consequence of using peer to peer transmission to receive a copy likewise does not require accep tance However nothing other than this License grants you permission to propagate or modify any
154. ee software because free software needs free documentation a free program should come with manuals providing the same freedoms that the software does But this License is not lim ited to software manuals it can be used for any tex tual work regardless of subject matter or whether it is published as a printed book We recommend this License principally for works whose purpose is instruction or reference 1 APPLICABILITY AND DEFINITIONS This License applies to any manual or other work in any medium that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License Such a notice grants a world wide royalty free license unlimited in dura tion to use that work under the conditions stated herein The Document below refers to any such manual or work Any member of the public is a li censee and is addressed as you You accept the license if you copy modify or distribute the work in a way requiring permission under copyright law A Modified Version of the Document means any work containing the Document or a portion of it ei ther copied verbatim or with modifications and or translated into another language A Secondary Section is a named appendix or a front matter section of the Document that deals ex clusively with the relationship of the publishers or authors of the Document to the Document s overall subject or to related matters and contains noth ing that could f
155. eformatted files e re invented the wheel by implementing features that already exist e added 160MB MPI trace files into the git repository See Phabricator s Advantages of Review document a Facebook project 17 2 Goals Our primary goals for code reviewing ROSE are to e share knowledge about the code coder reviewer will know the code instead of just the coder e group study learn through studying other peoples code http www phabricator com docs phabricator article User_Guide_Review_vs_Audit html advantages of review 116 Software e enforce policies for consistent usability and maintainability of ROSE code documented and tested e avoid reinventing the wheel and eliminating unnecessary redundancy e safe guarding the code disallowing subversive attempts to disable or remove regression tests 17 3 Software We are currently testing Github Enterprise and looking into the possibility of leveraging Redmine for internal code review In the past we have looked at Google s Gerrit code review system 17 3 1 Github Releases https enterprise github com releases Support https support enterprise github com rosebot Under development An automated pull request analyzer to perform various tasks e Automatically add reviewers to Pull Requests based on hierarchical configuration e Pre receive hook analyses file sizes quantity of files proprietary source etc e more 17 4 Developer Checklist
156. en wikibooks org wiki Help Print_versions 28 3 Maintain the better pdf file The pdf version automatically generated from the print version page is rudimentary It has no table of content and pagination etc So we used a manual process to generate better pdf file We need to occasionally repeat this process to have a up to date and better pdf file Here are the manual steps 1 Chapter on page 1 205 TODO List e Use your web browser to open and save the print version to your own computer as web page complete use the HTML compatible word processor of your choice to open the html file convert html to a format the word processor and add paginate the book e In Microsoft Word this can done by opening the saved HTML file saving it to a word file adding table of content by selecting Insert gt Field gt Index and Tables gt TOC or Preferences gt Table of contents for Word 2012 or later adding page numbers to the footer save it to a pdf file with a name like ROSE_ Compiler _Framework pdf upload to wikibooks To add a link to your wikibook page insert PDF version pdf file name without pdf size kb number pages file description For example PDF version ROSE_Compiler_Framework 840 kb 48 pages ROSE_Compiler_Framework More background about pdf verions at http en wikibooks org wiki Help Print_ versions 28 4 Documentation Alternatives 1 Google Docs comments different output formats easy
157. er clarity and productivity Abbreviations and acronyms should NOT be uppercase when used as name e exportHtmlSource NOT exportHTMLSource 97 Coding Standard e openDvdPlayer NOT openDVDPlayer Likewise commonly lowercase abbreviations and acronyms should NOT start with a lower case letter when used in a CamelCase name e SgAsmX86Instruction NOT SgAsmx86Instruction e mylpod NOT myiPod 16 6 3 File Directory Case e camelCase like fileName hpp This is consistent with existing names used in ROSE File Extension e Header files h or hpp e Source files cpp or cxx e C should be avoided to work with file systems which do not distinguish between lower or upper case 16 6 4 Namespaces e A namespace should represent a logical unit usually encapsulated in a single header file within a specific directory e CamelCase for namespaces such as Sagelnterface SageBuilder etc e avoid lower case names bad names sage_interface e use singular for nouns within namespace names avoid plural e use full words avoid abbreviations e use at least two words to reduce name collision Reason the name convention of namespace is meant to be compatible with existing code and consistent with function names within namespaces e CamelCase namespace can nice be used with doSomething like NameS pace doSomething e lower case namespace names may look inconsistent such as name_space_ 1 doSomething
158. error from runtime to compile time e use double 64 bits rather than float 32 bits precision loss is real performance loss negligible e consistent ordering include lt string h gt char strcpy char dest char src void bcopy void src void dst int n bad short parameter lists 3 or fewer more and users will have to refer to docs identically typed params harmful 201 Good API Design e Two techniques for shortening 1 break up method 2 create helper class to hold parameters 26 3 6 Return Values e Avoid values that demand exceptional processing gt For example return a zero length array or empty collection not null 26 3 7 Exceptions e don t force client to use exceptions for control flow e don t fail silently e favor unchecked exceptions e include failure capture diagnostic information e Fail fast report errors ASAP e Compile time static typing generics e Run time error on first bad method invocation should be failure atomic 202 27 Who is using ROSE We are aware of the following ROSE users people who write their own ROSE based tools They are the reason of the ROSE s existence Feel free to add your name if you are using ROSE 27 1 Universities e University of California San Diego CUDA code generator link e University of Utah compiler based parameterized code transformation for autotuning e University of Oregon performance too
159. ess If you don t have access to the EDG source code you will be able to automatically download a packaged EDG binary tarball during the ROSE build process The download is triggered during make in ROSE_BUILD src frontend CxxFrontend The EDG binary version is a computed binary compatibility signature relative to your version of ROSE You can check this version by running the ROSE scripts bincompat sig for example scripts bincompat sig 7b1930fafc929de85182ee1a14c86758 You may encounter this error scripts bincompat sig Unable to find a remote tracking a canonical repository Please add a canonical repository as a remote and ensure it is up to date Currently configured remotes are origin gt https github com rose compiler rose 12 EDG tarball Potential canonical repositories include anything ending with rose git case insensitive If you do simply add git to the end of your origin s URL path In our example this translates to https github com rose compiler rose git 3 5 2 List of binaries View the list of available EDG binaries here http www rosecompiler org edg_ binaries edg_binaries txt EDG binaries are generated for these platforms Last updated on 12 22 2012 Platform EDG 3 3 EDG 4 0 amd64 linux GCC 3 4 6 4 0 4 4 1 2 GCC 3 4 6 4 0 4 4 1 2 4 2 4 4 3 2 4 4 1 4 2 4 4 3 2 4 4 1 i686 linux GCC 3 4 6 4 0 4 4 1 2 GCC 3 4 6 4 0 4 4 1 2 4 2 4 4 3 2 4 4 1 4 2 4
160. etString lt lt Q n iterate over all the nodes in this function for VirtualCFG iterator it funcCFGStart it VirtualCFG dataflow end it DataflowNode n it The number of NodeStates associated with the given dataflow node int numStates NodeState numNodeStates n The actual NodeStates associated with the given dataflow node const vector lt NodeState gt nodeStates NodeState getNodeStates n Visit each CFG node for vector lt NodeState gt const_iterator itS nodeStates begin itS nodeStates end itS visit func n itS return false example retrieve the liveness analysis s IN lattice void getAllLiveVarsAt LiveDeadVarsAnalysis ldva const NodeState amp state set lt varID gt amp vars string indent e LiveVarsLattice liveLAbove dynamic_ cast lt LiveVarsLattice gt state getLatticeAbove ldva begin 11 4 Lattices Caveat lattice vs lattice value e A lattice by definition is a set of values However an instance of lattice type in Generic dataflow framework is used to represent an individual value within a lattice also Sorry for this confusing We welcome suggestions to fix this 11 4 1 Basics See more at ROSE Compiler Framework Lattice Store the data flow analysis information attached to CFG nodes Fundamental operations 5 Chapter 24 on page 191 53 Generic Dataflow Framework e what to store lattice value set bottom up
161. f functionality as far as the rest of the system is concerned In other words incremental development is about making one s work valuable as early as possible and potentially about getting a better sense of what direction it should take while continuous integration is about reducing the risks that result from codebase divergence as multiple people do development in parallel The question of whether to conditionalize new code is an interesting one By doing so one narrows the scope of continuous integration to just checking for surface incompatibilities in merging the changed code Without actually running the new code against the existing tests the early detection of introduced bugs is lost In exchange multiple people working in the same part of the codebase become less likely to step on each other s toes because the relevant code changes are distributed more rapidly See more at Continuous Integration 15 3 High Level Workflow 15 3 1 Requirement Analysis e External https github com rose compiler rose start an issue to be discussed e Wikibook e collect community input e mailing list interaction with users feel users need 15 3 2 Design e Wikibook community based design documents and provoke discussion e Powerpoint slides more formal communication about what is the design 15 3 3 Implementation e Redmine http hudson rose 30 3000 create projects based on milestones and user input create and track tasks 2
162. fault so the translators shipped with ROSE should already have debugging information available Note the compiler linking will take longer when debugging support is enabled However ROSE uses libtool so the executables in the build tree are not real they re simply wrappers around the actual executable files You have two choices e Find the real executable in the lib directory then debug the real executables there e Use libtool command line as follows libtool mode execute gdb args built_in_translator filel c The remaining steps are the same as a regular gdb session with the typical operations such as breakpoints printing data etc Example 1 Fixing a real bug in ROSE 1 Reproduce the reported bug make check 167 How tos testVirtualCFG edg no_warnings w rose verbose 0 edg restrict I ROSE tests CompileTests virtualCFG_tests Cxx_tests I ROSE sourcetree tests CompileTests A Code c ROSE sour cetree tests CompileTests virtualCFG_tests Cxx_tests test2001_01 C lt testVirtualCFG ROSE src frontend SagellI virtualCFG virtualCFG h 111 VirtualCFG CFGEdge CFGEdge VirtualCFG CFGNode VirtualCFG CFGNode Assertion src getNode failed _null amp amp tgt getNode __null Ah so we ve failed an assertion within the virtualCFG h header file on line 111 Assertion src getNode __null 48 tgt getNode __null failed And the error was produced by runn
163. fect AnalysisTests 10 7 Generic Dataflow Framework As the ROSE project goes on we have collected quite some versions of dataflow analysis It is painful to maintain and use them as they e Duplicate the iterative fixed point algorithm e Scatter in different directories and e Use different representations for results An ongoing effort is to consolidate all dataflow analysis work within a single framework Quick facts e Original author Greg Bronevetsky e Code reviewer Chunhua Liao e Documentation e Source codes files under src midend programAnalysis genericDataflow e Tests tests roseTests programAnalysisTests generalDataFlowAnalysisTests e Currently implemented analysis e Dominator analysis dominatorAnalysis h dominatorAnalysis C e Livedead variable analysis or liveness analysis liveDeadVarAnalysis h liveDead Var Analysis C e Constant propagation constantPropagation h constantPropagation C TODO need to move the files into src from tests See more at Generic Dataflow Framework 10 8 Dependence analysis TODO it turns out the interface work is not merged into our master branch So the following instructions do not apply The interface for dependence graph could be found in DependencyGraph h The underlying representation is n DepGraph h BGL is required to access the graph 8 Chapter 11 on page 49 46 Dependence analysis Here are 6 examples attached with this email In deptest C there are also some macr
164. for a GUI interface you would use an about box You should also get your employer if you work as a programmer or school if any to sign a copyright disclaimer for the program if nec essary For more information on this and how to apply and follow the GNU GPL see lt http www gnu org licenses gt The GNU General Public License does not permit incorporating your program into proprietary pro grams If your program is a subroutine library you may consider it more useful to permit linking pro prietary applications with the library If this is what you want to do use the GNU Lesser General Public License instead of this License But first please read lt http www gnu org philosophy why not lgpl html gt must enclose the copies in covers that carry clearly and legibly all these Cover Texts Front Cover Texts on the front cover and Back Cover Texts on the back cover Both covers must also clearly and legibly identify you as the publisher of these copies The front cover must present the full title with all words of the title equally prominent and visible You may add other material on the covers in addition Copying with changes limited to the covers as long as they preserve the title of the Doc ument and satisfy these conditions can be treated as verbatim copying in other respects If the required texts for either cover are too volu minous to fit legibly you should put the first ones listed as man
165. h ROSE_INSTALL path to rose installation ROSE uses the BOOST C libraries the prefix path BOOST_INSTALL path to boost installation 164 How to set up the makefile for a translator Your translator TRANSLATOR my_translator TRANSLATOR_SOURCE TRANSLATOR cpp Input testcode for your translator TESTCODE input_code_ifs cpp all TRANSLATOR compile the translator and generate an executable g is recommended to be used by default to enable debugging your code TRANSLATOR TRANSLATOR_SOURCE g g TRANSLATOR_SOURCE o TRANSLATOR I BOOST_INSTALL include I ROSE_INSTALL include L ROSE_INSTALL lib lrose test the translator check TRANSLATOR TRANSLATOR c I I ROSE_INSTALL include TESTCODE clean rm rf TRANSLATOR o rose_ dot 20 7 4 A complete example The sample Makefile prepared within ROSE virtual machine image demo ubuntu myTranslator cat makefile A sample Makefile to build a ROSE tool Important remember that Makefile recipes must contain tabs lt target gt lt dependency gt lt TAB gt lt command gt lt endl gt So you have to replace spaces with Tabs if you copy amp paste this file from a browser ROSE installation contains HH libraries e g librose la headers e g rose h ROSE_INSTALL home demo opt rose inst ROSE uses the BOOST C libraries BOOST_INSTALL home demo
166. hat is part of the Library You may convey such object code un der terms of your choice provided that if the in corporated material is not limited to numerical pa rameters data structure layouts and accessors or small macros inline functions and templates ten or fewer lines in length you do both of the follow ing a Give prominent notice with each copy of the object code that the Library is used in it and that the Library and its use are covered by this License b Accompany the object code with a copy of the GNU GPL and this license document Translation is considered a kind of modification so you may distribute translations of the Document under the terms of section 4 Replacing Invariant Sections with translations requires special permis sion from their copyright holders but you may in clude translations of some or all Invariant Sections in addition to the original versions of these Invari ant Sections You may include a translation of this License and all the license notices in the Document and any Warranty Disclaimers provided that you also include the original English version of this Li cense and the original versions of those notices and disclaimers In case of a disagreement between the translation and the original version of this License or a notice or disclaimer the original version will prevail If a section in the Document is Entitled Acknowl edgements Dedications or History the re quiremen
167. he debugging steps of your translator are just classic steps to use gdb e Make sure your translator is compiled with the GNU debugging option g so there is debugging information in your object codes These are the steps of a typical debugging session 1 Set a break point 2 Examine the execution path to make sure the program goes through the path that you expected 3 Examine the local data to validate their values how to print out information about a AST node 5 http gcc gnu org onlinedocs gcc Debugging Options html 166 How to debug a translator gdb print n 1 SgNode 0xb7f12008 Check the type of a node gdb print n gt sage_class_name 2 0x578b3af SgFile gdb print n gt get_parent 7 SgNode 0x95e75b8 Convert a node to its real node type then call its member functions When displaying a pointer to an object identify the actual derived type of the object rather than the declared type using the virtual function table gdb set print object on gdb print astNode 6 SgPragmaDeclaration 0xb7c68008 unparse the AST from a node Only works for AST pieces with full scope information It will report error if scope information is not available at any ancestor level gdb print n gt unparseToString print out Sg_File_Info gdb print n gt get_file_info gt display 20 8 2 A translator shipped with ROSE ROSE turns on debugging support by de
168. he print version of this wikibook Create a new page optional step create an account and log in Goto http en wikibooks org wiki ROSE_Compiler_Framework How tos Click on Edit tab on the right top of the How tos page Copy and paste one existing How to to the end of the page for example lt pre gt ROSE Compiler Framework How to write a How to How to write a How to ROSE Compiler Framework How to write a How to e rename three places of the pasted text with the desired page name for example ROSE Compiler Framework How to do XYZ How to do XYZ ROSE Compiler Framework How to do XYZ e click save page e You will see red text trying to link to the not yet existing How to do XYZ page e click any of the red text it will bring you to an editing window to add content of your new how to page 152 How to write a How to e you can now add new content and save it e Again each how to wiki page should NOT contain any level one or level two heading so it can be included at the correct levels in the print version of this wikibook 20 1 2 Insert image to wiki page e To use your own image in wiki page you have to upload the image to http commons wikimedia org e Once you upload the image it will become public to all wikibooks users Be sure to declare your copyright if the image is created by yourself e Following this instruction to insert image and adjust the layout of
169. he time needed to review your code should not exceed 1 hour Please avoid pushing thousands of lines at a time e Please also avoid pushing any trivial fixed a typo commented out a single line etc to be reviewed 17 4 2 One time setup Steps for initializing code review 1 Login to http github 11n1 gov using your OUN and PAC 2 Fork your own clone of the ROSE repository from http github 11n1 gov rose compiler rose e Go to http github 11n1 gov rose compiler rose e Click the Fork button at the upper right corner of the webpage 3 Add Collaborators e Go to http github 11n1 gov lt your_account gt rose 4 e Click Admin Click Collaborators e Add candidate code reviewers liao6 tool These developers will review and merge your work e Add admins hudson rose This user will automatically synchronize your master branch with nfs casc overture ROSE git ROSE git master Create your public private SSH key pair using ssh keygen and add the public key to your github IInl gov account Refer to Generating SSH Keys or use a public key tat you already have github llnl gov only supports the SSH protocol for now HTTPS is not yet supported 6 https help github com articles generating ssh keys 118 Developer Checklist 5 Configure Auto syncs Contact the Jenkins administrator tool and liao6 to have your repository added to a white list of repositories to be synced whenever new commits ar
170. her_it const bool operator const iterator amp it const 63 Generic Dataflow Framework 3 void iterator advance bool fwDir bool pushAllChildren ROSE_ASSERT initialized printf iterator advance d remainingNodes size d n fwDir remainingNodes size cout lt lt visited n for set lt DataflowNode gt iterator it visited begin it visited end it cout lt lt lt lt lt it gt getNode gt class_name lt lt lt lt it gt getNode lt lt lt lt it gt getNode gt unparseToString lt lt gt n if remainingNodes size gt 0 pop the next CFG node from the front of the list DataflowNode cur remainingNodes front remainingNodes pop_front if pushAllChildren find its followers either successors or predecessors depending on value of fwDir push back those that have not yet been visited vector lt DataflowEdge gt nextE if fwDir nextE cur outEdges else nextE cur inEdges for vector lt DataflowEdge gt iterator it nextE begin it nextE end it DataflowNode nextN it target need to put something here because DataflowNodes don t have a default constructor if fwDir nextN it target else nextN it source cout lt lt iterator advance lt lt fwDir descendant predecessor lt lt lt lt lt lt lt nextN getNode gt class_name lt lt lt lt nextN getNod
171. his is necessary for the how to page to be correctly included into the final one page print version of this wikibook Sorry about this restriction e Again please don t use level one or level two headings in a how to page Keep each how to short and focused Readers are expected to only spend 30 minutes or much less to quickly learn how to do something using ROSE After you created a new how to page and saved your contributions Please go to the print version to make sure it shows up correctly e Here is the link http en wikibooks org wiki ROSE_Compiler_Framework Print_version e Having new content show up in the print version will make sure it is really visible and consistent with the rest of the book please specify the how to topic is the current practice or the proposed new ways of doing things So we can have clear guideline for code review for what is mandatory and what is optional rename three places of the pasted text with the desired page name for example ROSE Compiler Framework How to do XYZ How to do XYZ dhunparserurl ROSE Compiler Framework How to do XYZ click save page You will see red text trying to link to the not yet existing How to do XYZ page click any of the red text it will bring you to an editing window to add content of your new how to page you can now add new content and save it e Again each how to wiki page should NOT contain any level one or level two heading so it can
172. ht line and a pointer to where the full notice is found lt one line to give the program s name and a brief idea of what it does gt Copyright C lt year gt lt name of author gt This program is free software you can redistribute it and or modify it under the terms of the GNU General Public License as published by the Free Software Foundation either version 3 of the Li cense or at your option any later version This program is distributed in the hope that it will be useful but WITHOUT ANY WAR RANTY without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PAR TICULAR PURPOSE See the GNU General Public License for more details You should have received a copy of the GNU Gen eral Public License along with this program If not see lt http www gnu org licenses gt Also add information on how to contact you by elec tronic and paper mail If the program does terminal interaction make it output a short notice like this when it starts in an interactive mode lt program gt Copyright C lt year gt lt name of au thor gt This program comes with ABSOLUTELY NO WARRANTY for details type show w This is free software and you are welcome to redistribute it under certain conditions type show c for details The hypothetical commands show w and show c should show the appropriate parts of the General Public License Of course your program s com mands might be different
173. hub rose buildtree src frontend CxxFrontend test d nfs casc overture ROSE git ROSE_ EDG_Binaries 8282 cp mfs casc overture ROSE git ROSE_ EDG_Binaries roseBinary EDG 3 3 i686 pc linux gnu GNU 4 4 32fe4e698c2e4a90dba3ee5533951d4c tar gz wget http www rosecompiler org edg_binaries roseBinaryEDG 3 3 1686 pc linux gnu GNU A 4 32fe4e698c2e4a90dba3ee5533951dAc tar gz 2012 08 05 12 58 29 http www rosecompiler org edg_binaries roseBinaryEDG 3 3 1686 pc linux gnu GNU 4 4 32fe4e698c2e4a90dba3ee5533951d4c tar gz Resolving www rosecompiler org 128 55 6 204 Connecting to www rosecompiler org 128 55 6 204 80 failed No route to host make 3 roseBinaryEDG 3 3 1686 pc linux gnu GNU 4 4 32fe4e698c2e4a90dba3ee5533951d4c tar gz Error 4 In this case you should ask for the missing tar ball or find it on our backup location e https github com rose compiler edg binaries You don t have to clone the entire edge binary repo since it is big You can just download the one you need click raw file link on github com Once you get the bar ball copy it to your build tree s CxxFrontend subdirectory e buildtree src frontend CxxFrontend Then you should be able to normally build rose by typing make TODO automate the search using the alternative path to obtain edg binary Another possible reason is that you cloned your local rose repo from an unofficial repository e In order to maintain the correct matching between rose source a
174. ict 3 Finally if all else fails force the synchronization git push force origin nfs master refs heads master WARNING your master branch on Github will be overriden so make sure you have sufficient backups and take precaution Please simply follow the email s instructions to force the update of your Github s master branch 17 10 Past Software Experience In the past we have experimented with other code review tools 17 10 1 Gerrit Google In short e Gerrit s user interface is not user friendly it s complex and therefore more confusing This is true when compared to Github s Pull Request mechanism for code review e Gerrit s remote API was not mature enough to handle our workflow Additionally we had to hack several things in order to slightly suit our needs On the other hand Github has a great remote API which is easily accessible through Ruby scripting a very popular language for the domain of web interfaces and development e Gerrit is not as popular as Github which is important for our project to gain traction Also more people are familiar with Github so it makes it easier for them to use 17 11 TODO e TOP PRIORITY add pre screening Jenkins job before manual code review kicks in e Research install and test Facebook s Phabricator http phabricator org 125 Code Review Process 17 12 Connection to Jenkins See Continuous Integration Connection to Code Review 17 13 References e http
175. iki e This wikibook non official community documentation Editable by anyone aimed to supplement official documents and to collect tutorials FAQ and quick pointers to important topics 3 Obtaining ROSE 3 1 Git Repositories ROSE s source files are managed by git a distributed revision control and source code management system There are several ways to download the source tree 3 1 1 Internal Repos e Private Git Repositories Within LLNL e Private git repository hosted within Lawrence Livermore National Laboratory the internal file path is usr casc overture ROSE git ROSE git central repository of ROSE in most cases this is automatically updated by Jenkins only after incoming commits pass all regression tests e Private git repository hosted by github llnl gov used for daily pushes and code review accessible in LC LC does not permit SSH so you ll have to use HTTPS to clone repos there Note You may encounter SSL certificate problems If you do simply disable SSL verification in cURL using either export GIT_SSL_NO_VERIFY false or configuring git git config global http sslVerify false HTTP 401 is unauthorized access If you re not prompted for your username password in the Shell then you need to use X forwarding so the authentication windows will popup ssh X lt LC machine gt Otherwise create a netrc file with machine github 11nl gov login lt username gt password lt passwor
176. ile If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in documentation are documented even if no documentation was available Private class members and static file members will be hidden unless the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES EXTRACT_ALL YES If the value of the INPUT tag contains directories you can use the FILE_PATTERNS tag to specify one or more wildcard pattern like cpp and h to filter out the source files in the directories If left blank the following patterns are tested c cc CXX cpp c d java ii ixx ipp i inl h hh hxx hpp h idl odl cs php php3 inc m mm dox py f90 f for vhd vhdl FILE_PATTERNS cpp hpp The RECURSIVE tag can be used to turn specify whether or not 175 How tos subdirectories should be searched for input files as well Possible values are YES and NO If left blank NO is used RECURSIVE YES 3 Generate the Doxygen documentation Invoke from your top level directory doxygen Doxyfile 4 View and verify the HTML documentation firefox html index html amp 5 Add target to your Makefile am to generate the documentation PHONY docs docs doxygen Doxyfile TODO should be DOXYGEN 20 10 How to fix a bug If you are trying to fix a bug your own or a bug assigned to you to fix Here are high level steps to do
177. ill apply to the combination as such 14 Revised Versions of this License The Free Software Foundation may publish revised and or new versions of the GNU General Public Li cense from time to time Such new versions will be similar in spirit to the present version but may dif fer in detail to address new problems or concerns Each version is given a distinguishing version num ber If the Program specifies that a certain num bered version of the GNU General Public License or any later version applies to it you have the option of following the terms and conditions either of that numbered version or of any later version published by the Free Software Foundation If the Program does not specify a version number of the GNU General Public License you may choose any version ever published by the Free Software Foun dation If the Program specifies that a proxy can decide which future versions of the GNU General Public License can be used that proxy s public statement of acceptance of a version permanently authorizes you to choose that version for the Program Later license versions may give you additional or different permissions However no additional obli gations are imposed on any author or copyright holder as a result of your choosing to follow a later version 15 Disclaimer of Warranty THERE IS NO WARRANTY FOR THE PRO GRAM TO THE EXTENT PERMITTED BY AP PLICABLE LAW EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPY
178. ing Source for the Combined Work excluding any source code for portions of the Combined Work that considered in isolation are based on the Application and not on the Linked Version The Corresponding Application Code for a Com bined Work means the object code and or source code for the Application including any data and utility programs needed for reproducing the Com bined Work from the Application but excluding the System Libraries of the Combined Work 1 Excep tion to Section 3 of the GNU GPL You may convey a covered work under sections 3 and 4 of this License without being bound by sec tion 3 of the GNU GPL 2 Conveying Modified Versions If you modify a copy of the Library and in your modifications a facility refers to a function or data to be supplied by an Application that uses the fa cility other than as an argument passed when the facility is invoked then you may convey a copy of the modified version under this License provided that you make a good faith effort to ensure that in the event an Ap plication does not supply the function or data the facility still operates and performs whatever part of its purpose remains meaningful or b under the GNU GPL with none of the additional permis sions of this License applicable to that copy 3 Object Code Incorporating Material from Li brary Header Files The object code form of an Application may incor porate material from a header file t
179. ing at least the title year new authors and publisher of the Modified Version as given on the Title Page If there is no section Entitled His tory in the Document create one stating the title year authors and publisher of the Document as given on its Title Page then add an item describ ing the Modified Version as stated in the previous sentence J Preserve the network location if any given in the Document for public access to a Trans parent copy of the Document and likewise the net work locations given in the Document for previous versions it was based on These may be placed in the History section You may omit a network lo cation for a work that was published at least four years before the Document itself or if the original publisher of the version it refers to gives permission K For any section Entitled Acknowledgements or Dedications Preserve the Title of the section and preserve in the section all the substance and tone of each of the contributor acknowledgements and or dedications given therein L Preserve all the Invariant Sections of the Document unaltered in their text and in their titles Section numbers or the equivalent are not considered part of the section titles M Delete any section Entitled Endorse ments Such a section may not be included in the Modified Version N Do not retitle any existing section to be Entitled Endorsements or to conflict in title with any Invariant Section O
180. ing the 1t testVirtualCFG libtool executable translator i e the actual translator name is testVirtualCFG without the 1t prefix 2 Run the same translator command line with Libtool to start a GDB debugging session libtool mode execute gdb args testVirtualCFG edg no_warnings w rose verbose 0 edg restrict I ROSE tests CompileTests virtualCFG_tests Cxx_tests I ROSE sourcetree tests CompileTests A Code c ROSE sour cetree tests CompileTests virtualCFG_tests Cxx_tests test2001_01 C GNU gdb GDB Red Hat Enterprise Linux 7 0 1 42 e15_8 1 Copyright C 2009 Free Software Foundation Inc License GPLv3 GNU GPL version 3 or later lt http gnu org licenses gpl html gt This is free software you are free to change and redistribute it There is NO WARRANTY to the extent permitted by law Type show copying and show warranty for details This GDB was configured as x86_64 redhat linux gnu For bug reporting instructions please see lt http www gnu org software gdb bugs gt Reading symbols from ROSE_BUILD_TRE E tests CompileTests virtualCFG_tests libs lt testVirtualCFG done gdb The GDB session has started and we re provided with a command line prompt to begin our debugging 3 Let s run the program which will hit the failed assertion gdb r Starting program ROSE_BU ILD_TREE tests CompileTests virtualCFG_tests libs lt testVirtualCFG edg no_warnings w rose ver
181. ing up rose config The rose config file integrates the project into the ROSE configure and build system At a minimum it should contain a call to the autoconf AC_CONFIG_ FILES macro with a list of the project s Makefiles without the am extension and its doxygen configuration file without the in extension It may also contain any other necessary autoconf checks that are not already performed by ROSE s main configure scripts including code to enable disable the project based on the availability of the project s prerequisites Here s an example dnl List of all makefiles and autoconf generated autoconf dnl files for this project AC_CONFIG_FILES projects DemoProject Makefile projects DemoProject gui Makefile projects DemoProject doxygen doxygen conf 1 dnl Even if this project is present in ROSE s projects directory we might not have the dnl prerequisites to compile this project Enable the project s makefiles by using the dnl ROSE_ENABLE_projectname automake conditional Many prerequisites have probably already dnl been tested by ROSE s main configure script so we don t need to list them here again dnl although it usually doesn t hurt AC_MSG_CHECKING whether DemoProject prerequisites are satisfied if test ac_cv_header_gcrypt_h yes then AC_MSG_RESULT yes rose_enable_demo_project yes else AC_MSG_RESULT no rose_enable_demo_project fi AM_CONDITIONAL ROSE_ENABLE_DEMO_PROJECT te
182. input test codes to ensure the contributions do what they are supposed to do e Is Jenkins being configured to trigger these tests your work may require new pre requisite software or configure options Local tests on developer s workstation do not count More details quick summary from Coding Standard Naming conventions File and directory names follow our standards clear and intuitive e Directory structure source code test code and documentation files are added into the correct locations Maintainability clarity of code can somebody who did not write the code easily understand what the code does e No looong functions a function with hundreds of lines of code is a no no e Architecture design the reasons and motivations for writing the code and its design No duplication similar code may already exist or can be extended Re use can part of the code be refactored to be reusable by others Unit tests make check rules are associated with each new feature to ensure the new feature will be tested and verified for expected behaviors Sanity no turning off or relaxing other tests to make the developer s commits pass Jenkins In other words no cheating 17 5 2 Commenting Reviewer comments should be clearly delimited into these three well defined sections 8 9 Chapter 16 on page 91 Chapter 16 on page 91 121 Code Review Process 1 Mandatory the details of the comment must be implemented in a new commit
183. inux Kernel sources https mailman nersc gov pipermail rose public 2011 April 000856 html Question I m trying to analyze the Linux kernel I was not sure of the size of the code base that can be handled by ROSE and could not find references as to whether it has been tried on the Linux kernel source As of now I m trying to run the identity translator on the source and would like to know if it can be done using ROSE and if it has been successfully tested before Short answer Not for now 140 AST Long answer We are using EDG 3 3 internally by default and this version of EDG does not handle the GNU specific register modifiers used in the asm statements of the Linux Kernel code There might be other problems but that was at least the one that we noticed in previous work on this some time ago But we are working on upgrading the EDG frontend to be a more recent version 4 4 19 2 6 Can ROSE compile C Boost library https mailman nersc gov pipermail rose public 2010 November 000544 htm1 not yet I know of a few cases where ROSE can t handle parts of Boost In each case it is an EDG problem where we are using an older version of EDG We are trying to upgrade to a newer version of EDG 4 x but that version s use within ROSE does not include enough C support so it is not ready The C support is internally tested but we need more time to work on this 19 3 AST 19 3 1 How to find XYZ in AST The usually steps to ret
184. ion Adding class declaration implementation into ROSE for the new IR nodes This step is mostly related to ROSETTA e Second step creation Creating those new IR nodes at some point such as somewhere within frontend midend or even backend if desired So this step is decided case by case If the new types of IR come from their counterparts in EDG then modifications to the EDG SAGE connection code are needed If not the EDG SAGE connection code may be irrelevant If you are trying to add new nodes to represent pragma information you can create your new nodes without involving EDG or its connection to ROSE You just parse the pragma string in the original AST and create your own nodes to get a new version of AST Then it should be done 19 3 7 How does the AST merge work tests that demonstrate the AST Merge are in the directory tests CompileTests mergeAST_tests run make check to see hundreds of tests go by 143 Frequently Asked Questions FAQ 19 3 8 parent vs scope An AST node can have a parent node which is different from the its scope For example the struct declaration s parent is the typedef declaration But the struct s scope is the scope of the typedef declaration typedef struct frame int x s_ frame 19 4 Translation 19 4 1 Can ROSE identityTranslator generate 100 identical output file https mailman nersc gov pipermail rose public 2011 January 000604 html Questions Rose iden
185. is discriminatory if it does not in clude within the scope of its coverage prohibits the exercise of or is conditioned on the non exercise of one or more of the rights that are specifically granted under this License You may not convey a covered work if you are a party to an arrangement with a third party that is in the business of dis tributing software under which you make payment to the third party based on the extent of your ac tivity of conveying the work and under which the third party grants to any of the parties who would receive the covered work from you a discrimina tory patent license a in connection with copies of the covered work conveyed by you or copies made from those copies or b primarily for and in connection with specific products or compilations that contain the covered work unless you entered into that arrangement or that patent license was granted prior to 28 March 2007 Nothing in this License shall be construed as ex cluding or limiting any implied license or other de fenses to infringement that may otherwise be avail able to you under applicable patent law 12 No Surrender of Others Freedom If conditions are imposed on you whether by court order agreement or otherwise that contradict the conditions of this License they do not excuse you from the conditions of this License If you cannot convey a covered work so as to satisfy simultane ously your obligations under this License
186. istent enough to make their contribution stick 17 6 Who should review what Ideally every ROSE contributor should participate in code review as a reviewer at some point so the benefits of peer review can fully be fulfilled However due to the limited access to our internal github enterprise server we currently have a centralized review process in which ROSE staff members liao6 tool serve as the default code reviewers They are responsible for either reviewing the code themselves or delegate to other developers who either has better knowledge about the contributions or should be aware of the contributions We am actively looking at better options and will gradually expand the pool of reviewers so the reviewing step won t become a bottleneck TODO use rosebot to automatically assign reviewers according to a hierarchical configura tion of the source tree 17 7 What to avoid e Judging code by whether it s what the reviewer would have written e Given a problem there are usually a dozen different ways to solve it And given a solution there s a million ways to render it as code e degenerating into nitpicks e perfectionism may hurt the progress we should allow some non critical improvements to be done in the next version commits e feel obligated to say something critical it is perfectly fine to say looks good pass e delay in review we should not rush it but we should keep in mind that somebody is waiting for the review to be do
187. ite new ones and improve existing ones e how ROSE works Tutorial manual FAQ etc e project documentation e design architecture api documents e workflow documentation etc e System administration Maintain and improve workflow components mostly not student s work but suggestions are welcomed e Website rosecompiler org e Git repository e Project management Redmine Code review Github enterprise e Jenkins Continuous integration improving testings Research e Publications technical reports papers presentations posters If you have finished your presentation please upload your slides to your relevant Redmine project s Files Tab pptx format is required since other people may want to edit it in the future Proposal e write collaborative proposals Feedback we are continually looking for ways to improve our workflow but there s always more that we can do e General struggles administratively or implementation wise e General improvement enhancement ideas for both the software and the people 14 3 Milestones for a ROSE developers Having been working with some interns with us we roughly identify the following milestones for a ROSE developer e Development environment pick a platform of your choice Linux or Mac OS and get familiar with that specific platform shell editors environment variable setting etc e Physical location locations MATTER Sit closer to people you should interact often Make yo
188. ite packages needed to build git from source files assuming you already installed GNU tool chain with GCC compiler make etc sudo apt get install gettext zlibig dev asciidoc libcurl4 openssl dev 1 Chapter 5 on page 21 10 EDG source code cd git enter the cloned git directory make configure as yourself configure prefix usr as yourself make all doc as yourself make install install doc install html as root 3 4 EDG source code If you have an EDG license we can provide you with ROSE s EDG source code The original official EDG source code does NOT work with ROSE since we have modified EDG to better serve our purposes Note We provide you with a snapshot of our Git revision controlled ROSE EDG source code repository This way you can more easily contribute your EDG modifications back into ROSE 1 Send your EDG research license to two ROSE staff members just in case one is on vacation or on travel 2 Provide ROSE staff with a drop off location for the EDG source code ssh or ftp server etc 3 Once you receive the EDG source code you have two options 3 4 1 As a submodule a Use ROSE EDG as a submodule assuming you have ROSE s Git source tree This is the recommended way to use the EDG git repo we provide So the assumption is that you use a local git clone of ROSE ROSE Edit submodule path in ROSE gitmodules to point to your ROSE EDG repository submod
189. ivalent access to the Corresponding Source in the same way through the same place at no further charge You need not require recipients to copy the Correspond ing Source along with the object code If the place to copy the object code is a network server the Cor responding Source may be on a different server op erated by you or a third party that supports equiv alent copying facilities provided you maintain clear directions next to the object code saying where to find the Corresponding Source Regardless of what server hosts the Corresponding Source you remain obligated to ensure that it is available for as long as needed to satisfy these requirements e Con vey the object code using peer to peer transmission provided you inform other peers where the object code and Corresponding Source of the work are be ing offered to the general public at no charge under subsection 6d A separable portion of the object code whose source code is excluded from the Corresponding Source as a System Library need not be included in conveying the object code work A User Product is either 1 a consumer prod uct which means any tangible personal property which is normally used for personal family or household purposes or 2 anything designed or sold for incorporation into a dwelling In deter mining whether a product is a consumer product doubtful cases shall be resolved in favor of cover age For a particular product rece
190. ived by a par ticular user normally used refers to a typical or common use of that class of product regardless of the status of the particular user or of the way in which the particular user actually uses or expects or is expected to use the product A product is a consumer product regardless of whether the prod uct has substantial commercial industrial or non consumer uses unless such uses represent the only significant mode of use of the product User Product authorization Installation Information for a means any methods procedures keys or other information required to install and execute modified versions of a covered work in that User Product from a modified version of its Corre sponding Source The information must suffice to ensure that the continued functioning of the modi fied object code is in no case prevented or interfered with solely because modification has been made If you convey an object code work under this sec tion in or with or specifically for use in a User Product and the conveying occurs as part of a transaction in which the right of possession and use of the User Product is transferred to the re cipient in perpetuity or for a fixed term regard less of how the transaction is characterized the Corresponding Source conveyed under this section must be accompanied by the Installation Informa tion But this requirement does not apply if neither you nor any third party retains the
191. ke your desk office accessible to others Physically isolated office desk may have very negative impact on your productivity 21 3 Choose your development platform carefully Lesson e Somehow new inters were assigned Mac OS X machines by default But some of them may not be familiar with Apple machines or even dislike Mac OS X s user interface including keyboard window system etc a love hate thing for Apple products So they felt stuck with an uncomfortable development platform We had interns who could not type smoothly on Mac keyboard even after one month This is unnecessary Solution 179 Lessons Learned e Provide choice up front Linux or Mac OS X Reminder people that they have freedom to choose the platform they personally enjoy 21 4 Use different git repositories for different tasks Lesson e A developer used different branches of the same git repository to do different tasks fixing bugs adding a new feature and documenting something Later on he found that he could not commit and push the work for one task since the changes for other tasks are not ready Solution using separated git repositories for different tasks So the status of one task won t interfere with the progress of other tasks 21 5 Introducing software dependencies very carefully Lesson e ROSE did not depend on boost C library in the beginning But later on some developers saw the benefits of Boost and advocated for it Eventually
192. kibook Create a new page optional step create an account and log in Goto http en wikibooks org wiki ROSE_Compiler_Framework How tos Click on Edit tab on the right top of the How tos page Copy and paste one existing How to to the end of the page for example lt pre gt ROSE Compiler Framework How to write a How to How to write a How to dhunparserurl ROSE Compiler Framework How to write a How to Quick short and focused tutorials about how to do common tasks as a ROSE developer Please create a new wikibook page for each how to topic Each how to wiki page should NOT contain any level one or level two heading so it can be included at the correct levels in the print version of this wikibook Create a new page optional step create an account and log in Goto http en wikibooks org wiki ROSE_Compiler_Framework How tos Click on Edit tab on the right top of the How tos page Copy and paste one existing How to to the end of the page for example lt pre gt ROSE Compiler Framework How to write a How to How to write a How to dhunparserurl ROSE Compiler Framework How to write a How to Quick short and focused tutorials about how to do common tasks as a ROSE developer Please create a new wikibook page for each how to topic Each how to wiki page should NOT contain any level one or level two heading so it can be included at the correct levels in t
193. l visit SgNode sgn SageBuilder pushScopeStack body SgAssignOp sao isSgAssignOp sgn if sao return SgVarRefExp svr SageBuilder buildVarRefExp mami SgIntVal siv SageBuilder buildIntVal 33 SgAssignOp newsao new SgAssignOp svr siv NULL SageInterface replaceWithPattern sao newsao SageBuilder popScopeStack The cause is SgAssignOp newsao new SgAssignOp svr siv NULL expr gt get_startOfConstruct NULL says there is no start file position There is an existing SageBuilder function to build Assign Op and take care of lots of details including file info objects Otherwise you have to maintain these details by yourself if you use raw new operators 37 10 Program Analysis ROSE have implemented the following compiler analysis call graph analysis e control flow graph e data flow analysis including liveness analysis def use analysis etc e dependence analysis e side effect analysis 10 1 control flow graph ROSE provides several variants of control flow graphs 10 1 1 Virtual Control Flow Graph The virtual control flow graph vcfg is dynamically generated on the fly when needed So there is no mismatch between the ROSE AST and its corresponding control flow graph The downside is that the same vcfg will be re generated each time it is needed This can be a potentially a performance bottleneck Facts e Documentation virtual CFG is documented in Chapter 1
194. l TAU e University of Wyoming OpenMP error checking e Tokyo Institute of Technology e RENCI RENaissance Computing Institute e Indian Institute of Technology Kanpur 27 2 DOE national laboratories e Argonne National Laboratory performance modeling 27 3 Companies e Samsung its research center at San Jose uses ROSE for multicore research and develop ment 1 http ege ucsd edu dokuwiki page doku php id didem projects mint 2 http www cs uoregon edu Research tau home php 203 28 TODO List What is missing so you can help if you want 28 1 How to backup mirror this wikibook Just in case this website is down how to download a backup of this wiki book How to set up a mirror wiki website containing the wikibook of ROSE 28 2 Maintain the print version It is possible that new chapters are added but they are not reflected in the one page print version So periodical synchronization is needed by including more chapters or re arranging their order in the one page print version Observations e A print version is similar to a source file with included contents each included chapter will have a first level of heading e Because the first level heading is used by the print version page to include all chapters all included pages chapters should NOT contain any first level heading With the basic understanding of how this work you can now edit the print version s wiki page e Print version More at http
195. lCFG dataflow IntraBWDataflow getInitialWorklist 11 7 4 apply transfer function b is a basic block in CFG e IN b Ubepreajo OUT p information goes into b is the union join of information comes out of all predecessor nodes of b e OUT b GEN b U IN b KILL b information goes out out S is the information generated by b minus information killed by b This is the transfer function operating on b bool IntraUniDirectionalDataflow runAnalysis const Function amp func NodeState fState bool analyzeDueToCallers set lt Function gt calleesUpdated Iterate over the nodes in this function that are downstream from the nodes added above for it itEnd it DataflowNode n it SgNode sgn n getNode for vector lt NodeState gt const_iterator itS nodeStates begin itS nodeStates end 65 Generic Dataflow Framework state itS const vector lt Lattice gt dfInfoAnte getLatticeAnte state IN set const vector lt Lattice gt dfInfoPost getLatticePost state OUT set OUT IN first transfer within the node from IN to OUT Overwrite the Lattices below this node with the lattices above this node The transfer function will then operate on these Lattices to produce the correct state below this node vector lt Lattice gt const_iterator itA itP int j 0 for itA dfInfoAnte begin itP dfInfoPost begin itA dfInfoAnte end amp
196. lator 20 6 How to create a cross language translator In this HOW to it presents the steps of generating a cross language translator We will use Fortran to C translator as an example here 2 Chapter 20 7 on page 163 161 How tos 20 6 1 Change the sourcefile information e change the output file name The suffix name has to be changed with this following function void SgFile set_unparse_output_filename std string unparse_output_filename e change the output language type void SgFile set_outputLanguage SgFile outputLanguage0ption_enum outputLanguage e Set the output to be target language only We use set_C_only for the Fortran to C translation This process might be optional void SgFile set_C_only bool C_only 20 6 2 Identify language dependent AST node Example ROSE AST uses different AST nodes to present a loop in C and Fortran The following two figures represent the same loop for different languages C uses SgForStatement for the for loops y f post rea Lee fret ham os tits om om pm sets ere fmt meio se par merc Joel aa P T j hs operand i originalExpresionTroe us operand i ype a esiatsqresiostc ersehen ecginalExpresion Tree canci n fs srini a N re r mbob fi gt fy gt x lt gt symbol gate gt gt nn AN VY j N
197. ld be named using the following pattern e LOGIN PURPOSE OPTION e NAME is typically a login name or surname e PURPOSE is a single word description of the type of work performed on that branch such as bugfixes e OPTION is information for ROSE robots with regards to your branch e test Changes to the branch are automatically tested e rc Changes are tested and if they pass then they re merged into the master branch like trunk in Subversion e EXAMPLE The matzke bugfixes rc branch is owned by Robb Matzke i e he s the one that generally makes changes to that branch it probably contains only bug fixes or minor 187 Git edits and it s being automatically tested and merged into the master branch for eventual release to the public 23 4 3 Commit messages It is important to have concise and accurate commit messages to help code reviewers do their work Example commit message excerpt from link Binary Analysis SMT solver statistics documentation Replaced the SMT class wide number of calls statistic with a more flexible and extensible design that also tracks the amount of I O between ROSE and the SMT solver The new method tracks statistics on a per solver basis as well as a class wide basis and allows the statistics to be reset at artibrary points by the user More documentation for the new memory cell memory state and X86 register state classes e Required Summary the first line of the commi
198. list before their termination Complete the student program checklist we have no idea what you need to do Complete the performance evaluation form provided by us mostly provide objective facts to demonstrate contributions since subjective impressions can be very off Complete a short feedback form provided by us where you can discuss anything related to developing ROSE or working with the ROSE team Your candid feedback is essential to the future of our collaborative program Schedule a one to one meeting with at least one staff member two weeks before the official end dates to do status check and plan the exit Turn in all documentations LaTeX word powerpoint etc not in git repo by uploading them to the redmine project File tab Stop developing any new features at least one week before the end date so we can focus on making sure all source code contributions can pass Jenkins If you plan to continue collaborating with us ask about getting internal access e g VPN or setup some other method for collaboration 14 5 code review See the Code Review section for details 1 2 3 Chapter 16 on page 91 Chapter 17 on page 115 Chapter 17 on page 115 85 Developer s Guide 14 6 Working from a Lab machine 14 6 1 Toolchain There are many tools pre installed on the nfs apps mount point ls nfs apps apr bin etc grace java mpc neon pygobject sqlite toolworks old asciidoc binutils flex graphviz libtool mpfr opens
199. ls other functions std set lt Function gt calleesUpdated return runAnalysis func state analyzeDueToCallers calleesUpdated 11 9 2 Through inter procedural analysis Invoke a simple intra procedural analysis through the unstructured pass inter procedural data flow class int main SgProject project frontend argc argv initAnalysis project prepare debugging support Dbg init Live dead variable analysis Test index html liveDeadAnalysisDebugLevel 1 analysisDebugLevel 1 basis analysis LiveDeadVarsAnalysis ldva project wrap it inside the unstructured inter procedural data flow UnstructuredPassInterDataflow ciipd_ldva amp ldva ciipd_ldva runAnalysis 11 9 3 Retrieve lattices Sample code Initialize vars to hold all the variables and expressions that are live at DataflowNode n void getAllLiveVarsAt LiveDeadVarsAnalysis ldva const DataflowNode amp n const NodeState amp state set lt varID gt amp vars string indent void getAllLiveVarsAt LiveDeadVarsAnalysis ldva const NodeState amp state set lt varID gt amp vars string indent 72 Testing LiveVarsLattice liveLAbove dy namic_cast lt LiveVarsLattice gt state getLatticeAbove ldva begin LiveVarsLattice liveLBelow dy namic_cast lt LiveVarsLattice gt state getLatticeBelow ldva begin The set of live vars AT this node is the union of vars that are live above it a
200. lt FunctionState gt allFuncs FunctionState getAllDefinedFuncs iterate over all functions with bodies for set lt FunctionState gt iterator it allFuncs begin it allFuncs end it t const Function amp func it gt func FunctionState fState FunctionState getDefinedFuncState func Call the current intra procedural dataflow as if it were a generic analysi intraAnalysis gt runAnalysis func amp fState gt state 11 8 4 ContextInsensitivelnterProceduralDataflow TODO 11 9 How to use one analysis 11 9 1 Call directly Direct call Runs the intra procedural analysis on the given function and returns true if the function s NodeState gets modified as a result and false otherwise state the function s NodeState 71 Generic Dataflow Framework e bool IntraUniDirectionalDataflow runAnalysis const Function amp func NodeState state bool analyzeDueToCallers std set lt Function gt calleesUpdated direct call with a simpler parameter list not feasible all intra procedural analysis has to have an inter procedural analysis set interally bool IntraProceduralDataflow runAnalysis const Function amp func NodeState state Each function is analyzed as if it were called directly by the language s runtime ignoring the application s actual call graph bool analyzeDueToCallers true We ignore the application s call graph so it doesn t matter whether this function cal
201. m and your own Doing a rebase prevents this and keeps the order in a more sane state 189 Git 23 7 References e http www kernel org pub software scm git docs gittutorial html e http book git scm com e http www sourcemage org Git_Guide more like a FAQ e http stackoverflow com questions 315911 git for beginners the definitive practical g 190 24 Lattices 24 1 Introduction Lattices are mathematical structures They can be used as a general way to express an order among objects This data can be exploited in data flow analysis Lattices can describe transformations effected by basic blocks on data flow values also known as flow functions Lattices can describe data flow frameworks when instantiated as algebraic structures con sisting of a set of data flow values a set of flow functions and a merge operator 24 2 Poset Partial ordering lt A partial ordering is a binary relation lt over a set P which is reflexive antisymmetric and transitive i e e Reflexive x lt x e Anti Symmetric if x lt y y lt x then x y e Transitive if x lt y y lt z then z lt z Partial orders should not be confused with total orders A total order is a partial order but not vice versa In a total order any two elements in the set P can be compared This is not required in a partial order Two elements that can be compared are said to be comparable A partially ordered set also known as a poset is a set with
202. may want to directly invoke the member functions of AST nodes and symbol tables to explicitly manipulate edges and symbols in the AST But this process is very tedious and error prone It is possible that some builder functions are not yet provided especially for C constructs like template declaration etc We are actively working on this In the meantime you can directly use new operators and other member functions as a workaround 9 4 Steps for writing translators Generic steps 35 Program Translation e prepare a simplest source file a c as an example input of your translator e avoid including any system headers so you can visualize the whole AST e use ROSE_INSTALLATION_TREE bin dotGeneratorWholeASTGraph to generate a whole AST for a c e prepare another simplest source file b c as an example output of your translator e again avoid including any system headers e use ROSE_INSTALLATION_TREE bin dotGeneratorWholeASTGraph to generate a whole AST for b c e compare the two dot graphs side by side e use Sagelnterface or SageBuilder functions to restruct the source AST graph to be the AST graph you want to generate e if there is no SageBuilder function to create what you want You may have to use new operator to create the nodes and take care of edges symbols yourself More details see How to create a translator 9 5 Order to traverse AST Naive pre order traversal is not suitable for building a translator since the translator m
203. nd EDG binary we require a canonical repository to be available make 3 Leaving directory global project projectdirs rosecompiler rose p roject workspace xomp instr buildtree src frontend CxxFrontend Clang Unable to find a remote tracking a canonical repository Please add a canonical repository as a remote and ensure it is up to date Currently configured remotes are origin gt git xxx com myrose git Potential canonical repositories include anything ending with rose git case insensitive Unable to find a remote tracking a canonical repository Please add a canonical repository as a remote and ensure it is up to date Currently configured remotes are origin gt git xxx com myrose git Potential canonical repositories include 138 Compilation anything ending with rose git case insensitive make 3 Entering directory global project projectdirs rosecompiler rose project workspace xomp instr buildtree src frontend CxxFrontend test d nfs casc overture ROSE git ROSE_EDG_Binaries amp amp cp nfs casc overture ROSE git RO SE_EDG_Binaries roseBinaryEDG 3 3 x86_64 pc linux gnu GNU 4 3 tar gz wget http www rosecompiler o rg edg_binaries roseBinaryEDG 3 3 x86_64 pc linux gnu GNU 4 3 tar gz 2013 02 15 17 26 42 http www rosecompiler o rg edg_binaries roseBinaryEDG 3 3 x86_64 pc linux gnu GNU 4 3 tar gz Resolving www rosecompiler org 128 55 6 204 Connecting to www rosecompiler org 128 5
204. nd below it for set lt varID gt iterator var liveLAbove gt liveVars begin var liveLAbove gt liveVars end var vars insert var for set lt varID gt iterator var liveLBelow gt liveVars begin var liveLBelow gt liveVars end var vars insert var 11 10 Testing It is essential to have a way to test the analysis results are correct We currently use a primitive way to test the correctness of analysis comparing pragma and lattice string output Two examples translators testing analysis correctness comparing pragma and lattice string output e https github com rose compiler rose blob master tests roseTests programAnalysisTests generalDataFlowAnalysisTests liveDeadVarAnalysisTest C e https github com rose compiler rose blob master tests roseTests programAnalysisTests generalDataFlowAnalysisTests constantPropagationTest C An example test input file for liveness analysis s correctness e https github com rose compiler rose blob master tests roseTests programAnalysisTests generalDataFlowAnalysisTests test5 C int bar int flag int a 1 b c pragma rose LiveVarsLattice liveVars flag a b if flag 0 flag is only read here not written c a else c b return c 73 Generic Dataflow Framework 11 11 How to debug 11 11 1 Trace the analysis Turn it on liveDeadAnalysisDebugLevel 1 analysisDebugLevel 1 find code with if analysisDebugLevel gt 1 check
205. ndex 0 most useful interface retrieve the lattices could be only one associated with a given analysis returns the map containing all the lattices from above the node that are owned by the given analysis read only access const std vector lt Lattice gt amp getLatticeAbove const Analysis analysis const returns the map containing all the lattices from below the node that are owned by the given analysis read only access const std vector lt Lattice gt amp getLatticeBelow const Analysis analysis const 11 3 4 FunctionState src midend programAnalysis genericDataflow state functionState h A pair of Function and NodeState ol Generic Dataflow Framework e it provides static functions to initialize all FunctionState And retrieve FunctionState class FunctionState friend class CollectFunctions public Function func NodeState state The lattices that describe the value of the function s return variables NodeState retState private static std set lt FunctionState gt allDefinedFuncs static std set lt FunctionState gt allFuncs static bool allFuncsComputed public FunctionState Function amp func func func state func get_declaration gt cfgForBeginning We should use this interface 1 returns a set of all the functions whose bodies are in the project static std set lt FunctionState gt amp getAllDefinedFuncs 2 return
206. ne to move forward 17 8 Criticism Code reviews often degenerate into nitpicks Brainstorming and design reviews to be more productive This makes sense the early we catch the problems the better Design happens earlier Design should be reviewed The same idea applies to requirement analysis also e To mitigate this risk we now have rules for design document in our coding standard 10 Chapter 16 3 on page 94 123 Code Review Process 17 9 Troubleshooting 17 9 1 master is out of sync The master branch of each developer s git repository http github 11n1 gov should be automatically synchronized with the central git repository s master branch nfs casc overture ROSE git ROSE git In rare cases it could be out of sync Here is an example to perform a manual synchronization 1 Clone your Github repository cd Development projects rose git clone git github com lt user_oun gt rose git Cloning into ROSE remote Counting objects 216579 done remote Compressing objects 100 55675 55675 done remote Total 216579 delta 159850 reused 211131 delta 155786 Receiving objects 100 216579 216579 296 41 MiB 35 65 MiB s done Resolving deltas 100 159850 159850 done 2 Add the central repository as a remote repository git remote add central nfs casc overture ROSE git ROSE git git fetch central From nfs casc overture ROSE git ROSE git new branch master gt central ma
207. ng any branches in your forked repo with any names you like If your local repository was cloned from nfs casc overture ROSE rose git There is no need to discard it You can just add the github 11nl s repo as an additional remote repository and push things there git remote add github 11n1 youraccount rose http github 11n1 gov youraccount rose git git push github 11n1 youraccount rose HEAD refs heads bugfix rc e e It is encouraged to push your work to a remote branch with a status suffix which will trigger a pre screening Jenkins Job http hudson rose 30 8080 view Status job SO pre screening before code review This is often useful to make sure your pushes can pass a minimum make check rules including your own before reviewers spend time on reading your code Reviewers can also see both your code and your code s actions e add a pull merge request to merge bugfix rc into your own fork s master 119 Code Review Process please note that the default pull request will use rose compiler rose s mas ter as the base branch destination of the merge Please change it to be your own fork s master branch instead Also make sure the source head branch of the pull merge request is the one your want bugfix re in this example Double check the diff tab of your pull request only shows the differences you made without other things brought in from the central repo Or your own repo s master is out of sync with the central
208. ng from a Lab machine 2 0000 86 Workflow 87 15 1 Motivation and Goals e 87 15 2 Development Guide opera Hama rer pa a 87 15 3 High Level Workflow 0 000002 eee ee eee 88 15 4 Proposing Workflow Changes 0 0000 eee eee 89 15 5 Reviewing Workflow Change Proposals 224 90 Coding Standard 91 16 1 What to Expect and What to Avoid 2 2 2 2m nme 91 16 2 Git Convention se A eo ee ee A eS 93 16 3 Design Document 94 16 45 Testing ns Bea ee ee u Be Balkan DU nn nen 96 16 5 Programming Languages aoaaa 97 16 6 Naming Conventions CC rn nn 97 lT Directories shoe su Bene Ge Ce Oe a E A 102 16 0 A Wie eae Genk A A A ee Bs ae et oe pt 103 T69 n README oa eee E Be OMS irae See Be ele Ber BY 105 16 10 Source Code Documentation 2 2 2 a Emm nn 106 16 21 Functions edo rara pik an Be Go 109 16 12 Comments u as GMA ee Rtg hoe de Bn aren de 109 16 13 Goding ce ara eee alle e Pe Meth Ss ee RO oe ee 109 16 14 CLASSES 2 a3 he oe a a ee Oe i o 109 16 15 Statements 24 2 ak Save ob koe eee ka os eS eae es 110 16 16 Expressions arn 2 02 22 en Si ee ee ee ee ds 113 16 17 AST Translators aa 113 16 18 References mon nee 113 Code Review Process 115 17 1 Motivation o a soaua a en ae 116 1102 Goals 528 gen Eee a en nei Met 116 10 3 IOOMWAre e a lo e e e ok ae ol ER o 117 17 4 Developer Checklist 2 222 2 o nn 1
209. ning From projects RosePoly 1 Version your project properly http semver org rosepoly_API_VERSION 0 1 0 2 Install to separate directory Installation tree should resemble lt prefix gt bin ROSE bin include ROSE include lib ROSE lib lt project gt lt version gt bin lt project gt bin include lt project gt include lib lt project gt lib exec_prefix prefix rosepoly rosepoly_API_VERSION Installation include tree should resemble lt project gt lt version gt bin lt project gt bin 6 http semver org 7 http github 11n1 gov rose compiler rose commit 30323b66bf af 53968f 140ac331b37a6732ddf8ab 174 How to add a new project directory include lt project gt include lt project gt lib lt project gt lib librosepoly_la_includedir exec_prefix include rosepoly 20 9 6 Generate Doxygen Documentation 0 Install Doxygen tool Using MacPorts for Apple s Mac OS port install doxygen set path to MacPort s bin Using one of the LLNL machines export PATH nfs apps doxygen latest bin PATH 1 Create a Doxygen configuration file doxygen g Configuration file Doxyfile created Now edit the configuration file and enter doxygen Doxyfile to generate the documentation for your project 2 Customize the configuration file Doxyf
210. nparse AST from headers right now A summer project tried to do this But it did not finish https mailman nersc gov pipermail rose public 2010 August 000344 html I guess ROSE does not support writing out changed headers for safety practical reasons A changed header has to be saved to another file since writing to the original header is very dangerous imaging debugging a header translator which corrupts input headers Then all other files headers using the changed header have to be updated to use the new header file Also all files involved have to be writable by user s translators As a result the current unparser skips subtrees of AST from headers by checking file flags compiler_ generated and or output _in_code generation etc stored in Sg_File_ Info objects 19 4 5 How to work with formal and actual arguments of functions https mailman nersc gov pipermail rose public 2011 June 001008 html Get the actual arguments SgExprListExp actualArguments NULL if isSgFunctionCallExp callSite actualArguments isSgFunctionCallExp callSite gt get_args else if isSgConstructorlnitializer callSite actualArguments isSgConstructorlnitializer callSite gt get_args ROSE_ASSERT actualArguments NULL const SgExpressionPtrList amp actualArgList actualArguments gt get_expressions Get the formal arguments SgInitializedNamePtrList formalArgList 146 Unparsing if calleeDef NULL formalArgLis
211. ny con ditions added under section 7 This requirement modifies the requirement in section 4 to keep in tact all notices c You must license the entire work as a whole under this License to anyone who comes into possession of a copy This License will therefore apply along with any applicable section 7 additional terms to the whole of the work and all its parts regardless of how they are packaged This License gives no permission to license the work in any other way but it does not invalidate such per mission if you have separately received it d If the work has interactive user interfaces each must display Appropriate Legal Notices however if the Program has interactive interfaces that do not dis play Appropriate Legal Notices your work need not make them do so A compilation of a covered work with other sepa rate and independent works which are not by their nature extensions of the covered work and which are not combined with it such as to form a larger program in or on a volume of a storage or distri bution medium is called an aggregate if the com pilation and its resulting copyright are not used to limit the access or legal rights of the compilation s users beyond what the individual works permit In clusion of a covered work in an aggregate does not cause this License to apply to the other parts of the aggregate 6 Conveying Non Source Forms You may convey a covered work in object code form un
212. o forbid circumvention of technologi cal measures to the extent such circumvention is ef fected by exercising rights under this License with respect to the covered work and you disclaim any intention to limit operation or modification of the work as a means of enforcing against the work s users your or third parties legal rights to forbid circumvention of technological measures 4 Con veying Verbatim Copies You may convey verbatim copies of the Program s source code as you receive it in any medium pro vided that you conspicuously and appropriately publish on each copy an appropriate copyright no tice keep intact all notices stating that this License and any non permissive terms added in accord with section 7 apply to the code keep intact all notices of the absence of any warranty and give all recipi ents a copy of this License along with the Program You may charge any price or no price for each copy that you convey and you may offer support or war ranty protection for a fee 5 Conveying Modified Source Versions You may convey a work based on the Program or the modifications to produce it from the Program in the form of source code under the terms of sec tion 4 provided that you also meet all of these con ditions a The work must carry prominent notices stating that you modified it and giving a relevant date b The work must carry prominent notices stating that it is released under this License and a
213. o opt jdk1 7 0_05 bin PATH lib path for libjvm so LD_LIBRAR Y_PATH LD_LIBRARY_PATH home leo opt jdk1 7 0_05 jre lib i386 server Don t forget to export both variables export PATH LD_LIBRARY_PATH 16 build 4 3 build In general it is better to rebuild the configure file in the top level source directory of ROSE Just type rose_sourcetree gt build 4 4 configure The next step is to run configure in a separated build tree ROSE will complain if you try to build it within its source directory There are many configuration options You can see the full list of options by typing sourcetree configure help But only prefix and with boost are required as the minimum options mkdir buildrose cd buildrose rose_sourcetree configure prefix home user opt rose_tux284 with boost home user opt boost 1 36 0 ROSE s configure turns on debugging option by default The generated object files should already have debugging information Additional useful configure options e Specify where a gcc s OpenMP runtime library libgomp a is located Only GCC 4 4 s gomp lib should be used to have OpenMP 3 0 support e with gomp_omp_runtime_library usr apps gcc 4 4 1 lib 4 5 make In ROSE s build tree type cd buildrose make j4 will build the entire ROSE including librose so tutorials projects tests and so on j4 means to use four processes to perform the build
214. oach this by checking the node for the specific SgFunctionDefinition or whatever you need and then check the name of the node to find its location 144 Translation e You can e use the AST query mechanism to find all functions and store them in a container e g Rose_STL_Container lt SgNode gt nodeList NodeQuery querySubTree root_ node V_Sg e Then iterate the container to check each function to see if the function name matches what you want e use SageBuilder namespace s buildFunctionCallStmt to create a function call state ment e use Sagelnterface namespace s insertStatement to do the insertion 19 4 3 How to copy clone a function https mailman nersc gov pipermail rose public 2011 April 000919 html We need to be more specific about the function you want to copy Is it just a prototype function declaration non defining declaration in ROSE s term or a function with a definition defining declaration in ROSE s term e Copying a non defining function declaration can be achieved by using the following function instead Build a prototype for an existing function declaration defining or nondefining is fine SgFunctionDeclaration SageBuilder buildNondefiningFunctionDeclaration const SgFunctionDeclaration funcdecl SgScopeStatement scope NULL Copying a defining function declaration is semantically a problem since it introduces re definition of the same function It is at least a hack to fir
215. oints by the user More documentation for the new memory cell memory state and X86 5 https github com rose compiler rose commit 801c53d81526e2eae7a68e0eab1a9f21b9892ab2 93 Coding Standard register state classes e Required Summary the first line of the commit message is a one line summary lt 50 words of the commit Start the summary with a topic enclosed in parentheses to indicate the project feature bugfix etc that this commit represents e Optional Use a bullet list using an asterisk for each item to elaborate on the commit Also see http spheredev org wiki Git_for_the_lazy Writing_good_commit_ messages 16 3 Design Document 16 3 1 Overview The software design document is a written contract between you your team your project manager and your client When you document your assumptions decisions and risks it gives the team members and stakeholders an opportunity to agree or to ask for clarifications and modifications Once the software design document is approved by the appropriate parties it becomes a baseline for limiting changes in the scope of the project How to Write a Software Design Document eHow com We are still in the process of defining the requirements for design documents but preliminarily here are the initial rules for writing a design document for a ROSE module an analysis transformation optimization etc We thank Professor Vivek Sarkar at Rice University
216. omed Contributions e Fix typos and grammar of existing pages to improve quality clarity and readability e Add new pages about ROSE specific tutorials how tos FAQ and workflow e Start discussions on the Discussion tab of an existing page about new suggestions of how things can be done better than the current practice e What will be not be kept Copy and paste of general guidelines of doing things Please just summary them in the ROSE relevant wikibook page and give reference URL to it Once you are certain the relevance of your contributions Please read how to do one example contribution e http en wikibooks org wiki ROSE_Compiler_Framework How_to_write_a_ How to e You can just test water how to edit in wikibook using http en wikibooks org wiki ROSE_Compiler_Framework Sandbox e Occasionally you may want to insert figures into a wiki page You can do this by uploading file first through Left menu gt Toolbox gt upload file 1 http en wikipedia org wiki ROSEY 20 28compiler 20framework 29 2 http en wikipedia org wiki Lawrence 20Livermore 20National 20Laboratory About the Book e The upload link will direct you to Media Commons more at link e Bottomline make sure your contributions are visible in the print version of this book and are logically consistent with the rest of the content e Link http en wikibooks org wiki ROSE_Compiler_Framework Print_version e Thank you 1 2 1 Conventions e Technical names iden
217. ompiler based tools A set of example tools are provided as part of the ROSE release to demonstrate the use of ROSE Some of them are also useful for daily work of ROSE developers We list and briefly explain some tools built using ROSE They are installed under ROSE_ INSTALLATION_TREE bin 6 1 prerequisites You have to install ROSE first by typing configure make make install etc You also have to set the environment variables properly before you can call ROSE tools from command line For example if the installation path or prefix path in configure is home opt rose install you can have the following script to set the environment variables using bash ROSE_INS home opt rose install export ROSE_INS PATH ROSE_INS bin PATH export PATH LD_LIBRARY_PATH ROSE_INS 1ib LD_LIBRARY_PATH export LD_LIBRARY_PATH 6 2 identityTranslator Source http www rosecompiler org ROSE_Tutorial ROSE Tutorial pdf chapter 2 This is the simplest tool built using ROSE It takes input source files builds AST and then unparses the AST back to compilable source code It tries its best to preserve everything from the input file 6 2 1 Uses Typical use cases e without any options test if ROSE can compile your code replace the compiler used by your Makefile with identityTranslator 25 ROSE tools e turn on some built in analysis translation or optimization phases such as rose openmp lowering to support OpenMP e typ
218. onal 16 15 3 Conditionals The body of a conditional must be put on a separate line if isDone NOT if isDone doCleanup doCleanup This is for debugging purposes When writing on a single line it is not apparent whether the test is really true or not There must be a space separating the keyword if from the condition statement isDone if isDone space Complex conditional expressions must be avoided You must introduce temporary boolean variables instead recommended way bool isFinished elementNo lt 0 elementNo gt maxElement bool isRepeatedEntry elementNo lastElement if isFinished isRepeatedEntry NOT if elementNo lt 0 elementNo gt maxElement elementNo lastElement 111 Coding Standard By assigning boolean variables to expressions the program gets automatic documentation The construction will be easier to read debug and maintain When the variables are well named it also helps future developers understand what each part of the construction is accomplishing 16 15 4 printf and cout All screen output MUST be put into a if statement to be conditionally executed either via verbose level or other debugging option They MUST not print out information by default TODO this can be enforced by a simple Compass checker in the future 16 15 5 switch Carefully differentiate e things which are known to be allowed to ignore
219. onding Application Code If you use option 4d1 you must provide the Installation Information in the manner specified by section 6 of the GNU GPL for conveying Corresponding Source this License can be used that proxy s public state ment of acceptance of a version permanently autho rizes you to choose that version for the Document 11 RELICENSING Massive Multiauthor Collaboration Site or MMC Site means any World Wide Web server that publishes copyrightable works and also pro vides prominent facilities for anybody to edit those works A public wiki that anybody can edit is an example of such a server A Massive Multiau thor Collaboration or MMC contained in the site means any set of copyrightable works thus pub lished on the MMC site CC BY SA means the Creative Commons Attribution Share Alike 3 0 license published by Creative Commons Corporation a not for profit corporation with a principal place of business in San Francisco California as well as future copyleft versions of that license published by that same organization Incorporate means to publish or republish a Doc ument in whole or in part as part of another Doc ument An MMC is eligible for relicensing if it is licensed under this License and if all works that were first published under this License somewhere other than this MMC and subsequently incorporated in whole or in part into the MMC 1 had no cover texts or invariant sections
220. opt boost 1 40 0 Your translator TRANSLATOR myTranslator TRANSLATOR_SOURCE TRANSLATOR cpp Input testcode for your translator TESTCODE hello cpp 4 Chapter 5 on page 21 165 How tos Makefile Targets all TRANSLATOR compile the translator and generate an executable g is recommended to be used by default to enable debugging your code Note depending on the version of boost you may have to use something like I BOOST_ROOT include boost 1_40 instead TRANSLATOR CTRANSLATOR_SOURCE g g TRANSLATOR_SOURCE I BOOST_INSTALL include I ROSE_INSTALL include L ROSE_INSTALL lib lrose o TRANSLATOR test the translator check TRANSLATOR TRANSLATOR c I I ROSE_INSTALL include TESTCODE clean rm rf TRANSLATOR o rose_ dot demo ubuntu myTranslator make check g g myTranslator cpp I home demo opt boost 1 40 0 include I home demo opt rose inst include L home demo opt rose inst lib lrose o myTranslator myTranslator c I I home demo opt rose inst include hello cpp 20 8 How to debug a translator It is rare that your translator will just work after your finish up coding Using gdb to debug your code is indispensable to make sure your code works as expected This page shows examples of how to debug your translator 20 8 1 A translator not built by ROSE s build system If the translator is built using a makefile without using libtool T
221. os to enable more accurate analysis If USE_IVS is defined the induction variable substitution will be performed if USE_ FUNCTION is defined the dependency could take a user specified function side effect interface Otherwise if non of them are defined it will perform a normal dependence analysis and build the graph 9 https mailman nersc gov pipermail rose public 2012 May 001620 html AT 11 Generic Dataflow Framework 11 1 Introduction As the ROSE project goes on we have collected quite some versions of dataflow analysis It is painful to maintain and use them as they duplicate the iterative fixed point algorithm scatter in different directories use different representations for results and has different level of maturity and robustness An ongoing effort is to consolidate all dataflow analysis work within a single framework Quick facts original author Greg Bronevetsky code gatekeeper Chunhua Liao Documentation e Chapter 18 Generic Dataflow Analysis Framework of the ROSE tutorial pdf git commit e This wikibook page source codes files under src midend programAnalysis genericDataflow tests tests roseTests program AnalysisTests generalDataFlowAnalysisTests 11 2 Implemented analysis List Constant Propagation dominator analysis dominatorAnalysis h dominatorAnalysis C livedead variable analysis or liveness analysis liveDeadVarAnalysis h liveDead VarAnaly sis C Pointer Analysis
222. ould discuss If you want to call me that would be the best way to proceed Send me email off of the main list and we can set that up https mailman nersc gov pipermail rose public 2011 March 000798 html Under Windows ROSE uses CMake This is a project that is currently under development As of November 2010 we are able to compile and link the src directory We are also able to run example programs that link against librose and execute the frontend and backend em However this is an internal capability and not available externally yet since we don t distribute the Windows generated EDG binaries that would be required Also the current support for Windows is still incomplete ROSE does not yet pass its internal tests under Windows 4 http www cmake org 149 20 How tos Quick short and focused tutorials about how to do common tasks as a ROSE developer Please create a new wikibook page for each how to topic Each how to wiki page should NOT contain any level one or level two heading so it can be included at the correct levels in the print version of this wikibook 20 1 How to write a How to Quick short and focused tutorials about how to do common tasks as a ROSE developer Please create a new wikibook page for each how to topic Each how to wiki page should NOT contain any level one or level two heading so it can be included at the correct levels in the print version of this wikibook 20 1 1 Create a new
223. perating system if any on which the executable work runs or a compiler used to produce the work or an object code interpreter used to run it The Corresponding Source for a work in object code form means all the source code needed to gen erate install and for an executable work run the object code and to modify the work including scripts to control those activities However it does not include the work s System Libraries or general purpose tools or generally available free programs which are used unmodified in performing those ac tivities but which are not part of the work For example Corresponding Source includes interface definition files associated with source files for the work and the source code for shared libraries and dynamically linked subprograms that the work is specifically designed to require such as by intimate data communication or control flow between those subprograms and other parts of the work The Corresponding Source need not include any thing that users can regenerate automatically from other parts of the Corresponding Source The Corresponding Source for a work in source code form is that same work 2 Basic Permissions All rights granted under this License are granted for the term of copyright on the Program and are irrevocable provided the stated conditions are met This License explicitly affirms your unlimited per mission to run the unmodified Program The out put from running a co
224. r conditions whatsoever to those of this License You may not use technical mea sures to obstruct or control the reading or further copying of the copies you make or distribute How ever you may accept compensation in exchange for copies If you distribute a large enough number of copies you must also follow the conditions in sec tion 3 You may also lend copies under the same condi tions stated above and you may publicly display copies 3 COPYING IN QUANTITY If you publish printed copies or copies in media that commonly have printed covers of the Doc ument numbering more than 100 and the Doc ument s license notice requires Cover Texts you fect according to their terms reviewing courts shall apply local law that most closely approximates an absolute waiver of all civil liability in connection with the Program unless a warranty or assumption of liability accompanies a copy of the Program in return for a fee END OF TERMS AND CONDITIONS How to Ap ply These Terms to Your New Programs If you develop a new program and you want it to be of the greatest possible use to the public the best way to achieve this is to make it free software which everyone can redistribute and change under these terms To do so attach the following notices to the pro gram It is safest to attach them to the start of each source file to most effectively state the exclu sion of warranty and each file should have at least the copyrig
225. rNodeState DataflowNode curNode int curNodelndex const vector lt Lattice gt amp nextNodeState DataflowNode nextNode bool modified false vector lt Lattice gt const_iterator itC itN if analysisDebugLevel gt 1 Dbg dbg lt lt n Propagating to Next Node lt lt nextNode getNode lt lt lt lt nextNode getNode gt class_name lt lt lt lt Dbg escape nextNode getNode gt unparseToString lt lt lt lt endl int j for j 0 itC curNodeState begin itC curNodeState end itCt j Dbg dbg lt lt Cur node Lattice lt lt j lt lt An lt lt itC gt str lt lt endl for j 0 itN nextNodeState begin itN nextNodeState end itN j Dbg dbg lt lt Next node Lattice lt lt j lt lt An lt lt GritN gt str lt lt endl F Update forward info above nextNode from the forward info below curNode Compute the meet of the dataflow information along the curNode gt nextNode edge with the next node s current state one Lattice at a time and save the result above the next node for itC curNodeState begin itN nextNodeState begin itC curNodeState end amp amp itN nextNodeState end itC itN Finite Lattices can use the regular meet operator while infinite Lattices must also perform widening to ensure convergence if itN gt finiteLattice modified itN gt meetUpdate itC modified else
226. raProceduralDataflow dfAnalysis std vector lt Lattice gt amp initState this gt dfAnalysis dfAnalysis void visit const Function amp func const DataflowNode amp n NodeState amp state Fs void InitDataflowState visit const Function amp func const DataflowNode amp n NodeState amp state dfAnalysis gt genInitState func n state initLats initFacts state setLattices Analysis dfAnalysis initLats state setFacts Analysis dfAnalysis initFacts 11 7 3 worklist list of CFG nodes accessed through an iterator interface auto_ ptr lt VirtualCFG dataflow gt workList getInitialWorklist func first Visit analyzeDue ToCallers calleesUpdated fState class iterator Declared in cfgUtils VirtualCFGIterator h public std list lt DataflowNode gt remainingNodes std set lt DataflowNode gt visited bool initialized protected returns true if the given DataflowNode is in the remainingNodes list and false otherwise bool isRemaining DataflowNode n advances this iterator in the given direction Forwards if fwDir true and backwards if fwDir false if pushAllChildren true all of the current node s unvisited children predecessors or successors depending on fwDir are pushed onto remainingNodes void advance bool fwDir bool pushAllChildren public virtual void operator int bool eq const iterator amp other_it const bool operator const iterator amp ot
227. ral Public License to permit their use in free software 5 Combined Libraries You may place library facilities that are a work based on the Library side by side in a single library together with other library facilities that are not Applications and are not covered by this License and convey such a combined library under terms of your choice if you do both of the following a Accompany the combined library with a copy of the same work based on the Library uncombined with any other library facilities conveyed under the terms of this License b Give prominent no tice with the combined library that part of it is a work based on the Library and explaining where to find the accompanying uncombined form of the same work 6 Revised Versions of the GNU Lesser General Public License The Free Software Foundation may publish revised and or new versions of the GNU Lesser General Public License from time to time Such new ver sions will be similar in spirit to the present version but may differ in detail to address new problems or concerns Each version is given a distinguishing version num ber If the Library as you received it specifies that a certain numbered version of the GNU Lesser Gen eral Public License or any later version applies to it you have the option of following the terms and conditions either of that published version or of any later version published by the Free Software Foun dation If the Library
228. re commits can break your contributions Programming Languages 16 5 Programming Languages 16 5 1 Core Languages Only C is allowed Any other programming language is an exception on a case by case basis Question But Programming language XYZ is much better than C and I am really good at XYZ Answer We can allow XYZ only if e You can teach at least one of old dogs staff members of our team the new tricks to efficiently use XYZ e You will be around in our team in the next 5 to 10 years to maintain all the code written in XYZ if none of the old dogs have time interest to switch to XYZ e You can prove that XYZ can interact well with the existing C codes in ROSE 16 5 2 Scripting Languages Only two scripting languages are allowed e bash shell scripting e perl Again this is just a preference of the staff members and what we have now Allowing uncontrolled number of scripting languages in a single project will make the project impossible to maintain and hard to learn 16 6 Naming Conventions The order of sub sections reflects a top down approach for how things are added during the development cycle from directory gt file gt namespace gt etc 16 6 1 General e Language all names should be written in English since it is the preferred language for development internationally fileName NOT filNavn 16 6 2 Abbreviations and Acronyms Avoid ambiguous abbreviations obtain good balance between us
229. re the environment variables PATH LD_LIBRARY_PATH for the installed rose are correctly set which dotGeneratorWholeASTGraph workspace masterClean build64 install bin dotGeneratorWholeASTGraph run the dot graph generator dotGeneratorWholeASTGraph c ttt c see it which run sh 64home opt zgrviewer 0 8 2 run sh run sh ttt c_WholeAST dot 8 3 Text Output of an AST Just call SgNode unparseToString You can call it from any SgLocatedNode within the AST to dump partial AST s text format 8 4 Preprocessing Information In addition to nodes and edges ROSE AST may have attributes in addition to nodes and edges that are attached for preprocessing information like include or if else They are attached before after or within a nearby AST node only the one with source location information An example translator will traverse the input code s AST and dump information which may include preprocessing information For example exampleTranslators defaultTranslator preprocessingInfoDumper c main cxx Found an IR node with preprocessing Info attached memory address 0x2b7e1852c7d0 Sage type SgFunctionDeclaration in file export tmp liao6 workspace userSupport main cxx line 3 column 1 o PreprocessingInfo 0 classification CpreprocessorIncludeDeclaration String format include all_headers h 32 AST Construction relative position is before Source http www rosecompiler org ROSE_Tutori
230. reate the virtual machine image uname a Linux 8core ubuntu 2 6 32 41 generic pae 91 Ubuntu SMP Wed Jun 13 12 00 09 UTC 2012 i686 GNU Linux cat etc release DISTRIB_ID Ubuntu DISTRIB_RELEASE 10 04 DISTRIB_CODENAME lucid DISTRIB_DESCRIPTION Ubuntu 10 04 4 LTS 5 2 2 Configurations VMware player has been installed onto the host machine as described above Basic configuration for the virtual machine 22 How to create a new virtual image Hardware e Memory 2 GB e Processors 2 e Hard Disk size 15 GB We would like to keep it small while having enough space for users e 5GB is used for Ubuntu system files and e 10GB for the demonstration user s home directory e Network Adapter NAT share the host s IP address OS e OS Ubuntu 10 04 LTS e Demonstration user account sudo user in Ubuntu e account demo e password password e screen size 1280x960 4 3 Download Ubuntu 10 04 LTS http releases ubuntu com lucid We currently use the i386 desktop ISO as the start point e http releases ubuntu com lucid ubuntu 10 04 4 desktop i386 iso 5 2 3 Within the virtual machine We installed Software Prerequisites e sudo apt get install gcc g gfortran e sudo apt get install autoconf automake libtool e sudo apt get install git core bison flex texlive full graphviz python all dev We then installed ROSE e See ROSE installation for details about how this was done 5 3 How to create a new virtual image
231. ree src frontend Sagelll Cxx_Grammar h has function prototypes for adding CFGEdge of SgOmpClause like SgOmpClause cfgInEdge SgOmpClause cfgOutEdge If there is no prototypes then that means you CFGNode does not belong to SgExpression SgStatement and SgExpression SgOmpClause can be added in src ROSETTA Grammar Support code e 2 add the function definitions in src frontend SagelII virtualCFG memberFunctions C to give the definitions of adding CFGNode and CFGEdge step1 construct SgOmpClause cfgndexForEnd this index is based on the AST graph of your source code the index is explicit in AST node real example SgOmpClauseBodyStatement cfgIndexForEnd const int size this gt get_clauses size the number of clauses in pragma omp parallel return size 1 clauses body step2 construct cfgInEdge for this CFGNode please refer to AST since AST can show all node information real example std vector lt CFGEdge gt SgOmpClauseBodyStatement cfgInEdges unsigned int idx std vector lt CFGEdge gt result addIncomingFortranGotos this idx result if idx 0 makeEdge getNodeJustBeforeInContainer this CFGNode this idx result else 40 control flow graph if idx this gt get_clauses size 1 makeEdge this gt get_body gt cfgForEnd CFGNode this idx result connect variables clause
232. riate state transfers across function boundaries 11 8 1 transfer function void IntraFWDataflow transferFunctionCall const Function amp func const DataflowNode amp n NodeState state vector lt Lattice gt dfInfoBelow state gt getLatticeBelow this vector lt Lattice gt retState NULL dynamic_cast lt InterProceduralDataflow gt interAnalysis gt transfer func n state dfInfoBelow amp retState true if retState amp amp retState gt size 0 retState gt size dfInfoBelow size Dbg dbg lt lt retState lt lt retState gt size lt lt endl for vector lt Lattice gt iterator ml retState gt begin ml retState gt end ml Dbg dbg lt lt lt lt 4ml gt str lt lt endl Dbg dbg lt lt dfInfoBelow lt lt dfInfoBelow size lt lt endl for vector lt Lattice gt const_iterator 1 dfInfoBelow begin 1 dfInfoBelow end 1 Dbg dbg lt lt lt lt 1 gt str lt lt endl Incorporate information about the function s return value into the caller s dataflow state as the information of the SgFunctionCallExp ROSE_ASSERT retState NULL retState gt size 0 retState gt size dfInfoBelow size if retState vector lt Lattice gt iterator 1Ret vector lt Lattice gt const_iterator 1DF for 1Ret retState gt begin 1DF dfInfoBelow begin lRet retState gt end 1lRet 1DF Dbg dbg lt lt 1DF Before
233. ries tests roseTests src frontend tests CompileTests Fortran_tests tests CompilerOptionsTests docs tests CompileTests RoseExample_tests src midend docs Rose winspecific ROSE_ResearchPapers tests CompileTests Fortran_tests gfortranTestSuite binaries samples binaries tests CompileTests Fortran_tests gfortranTestSuite gfortran dg 14 11 10 10 10 10 mm mn DD oa JAJAJAA AJO src roseExtensions projects traceAnalysis tests CompileTests A Code tests CompilerOptionsTests testCpreprocessor0ption tests CompilerOptionsTests A Code src roseExtensions qtWidgets src frontend Disassemblers projects symbolicAnalysisFramework projects SATIrE projects compass winspecific MSVS_ROSE tests RunTests A Tests tests roseTests binaryTests src frontend SageIII projects symbolicAnalysisFramework src docs Rose powerpoints winspecific MSVS_project_ROSETTA_empty projects simulator tests RunTests FortranTests LANL_POP_OLD tests CompileTests Cxx_tests src midend programTransformation src midend programAnalysis src 3rdPartyLibraries libharu 2 1 0 scripts projects symbolicAnalysisFramework src mpiAnal projects RTC winspecific MSVS_ROSE Debug tests RunTests FortranTests LANL_POP netcdf 4 1 1 ncdap_test tests roseTests programAnalysisTests src 3rdPartyLibraries ckpt src 3rdPartyLibraries antlr jars projects SATIrE src tests RunTests Fortr
234. rieve information from AST are e prepare a simplest preferrably 5 10 lines only compilable sample code with the code feature you want to find e g array i j if you are curious about how to find use of multi dimensional arrays in AST avoid including any headers include file h to keep the code small e Please note don t include any headers in the sample code A header include lt stdio h gt for example can bring in thousands of nodes into AST e use dotGeneratorWholeASTGraph to generate a detailed AST dot graph of the input code e use zgrviewer 0 8 2 s run sh to visulize the dot graph e visually manually locate the information you want in the dot graph understand what to look and where to look e use code AST member functions traversal Sagelnteface functions etc to retrieve the information 19 3 2 How to filter out header files from AST traversals https mailman nersc gov pipermail rose public 2010 April 000144 html Question I want to exclude functions in include files from my analysis transformations during my processing By default AST traversal may visit all AST nodes including the ones come from headers So AST processing classes provide three functions 141 Frequently Asked Questions FAQ T traverse SgNode include files T traverselnputFiles SgProject projectNode traverse the subtree of AST which represents the files specified on the command line T traverseWithinFile SgNode
235. roved pull merge request If there is any new approved commits the job will transfer the commits to the central repository s reviewed rc branch for that developer Configuration of the auto pull job e Source code management e git gitQ github IInl gov account_name rose git e branches to be build github master e Build Trigger Poll SCM schedule e Execution shell HH Add nfs as remote HH true don t error if remote exists 3 Chapter 17 on page 115 130 TODO HH git remote add nfs nfs casc overture ROSE git ROSE git true git fetch nfs HH Push to nfs rc HH if n git log oneline nfs master github master then git push force nfs GIT_BRANCH refs heads oun reviewed rc fi 18 7 2 Auto Push Auto push A Jenkins job is responsible for propagating latest central master contents to all private repositories on github linl gov e http hudson rose 30 8080 job Commit sync github The Job configuration e source Code Management e Git nfs casc overture ROSE git ROSE git e Branches to build master e Build Trigger Build after other projects are built Commit e Execute Shell USERS user1 user2 for user in USERS do tmpfile mktemp git push git github 11nl gov user rose git origin master refs heads master 2 gt tmpfile true set te cat tmpfile cat tmpfile grep q non fast forward if eq 0 then echo
236. s 10 1 3 Static and Interprocedural CFGs Facts e Documentation 19 8 Static Interprocedural CFGs of ROSE tutorial pdf e Test Directory rose tests CompileTests staticCFG_ tests 10 2 Virtual Function Analysis Facts e Original contributor Faizur from UTSA done in Summer 2011 e Code at src midend programAnalysis VirtualFunctionAnalysis e Implemented with the techniques used in the following paper Interprocedural Pointer Alias Analysis http citeseerx ist psu edu viewdoc summary doi 10 1 1 42 2382 The paper boils down the virtual function resolution to pointer aliasing problem The paper employs flow sensitive inter procedural data flow analysis to solve aliasing problem using compact representation graphs to represent the alias relations e Some test files in the roseTests folder of the ROSE repository and he told me that the implementation supports function pointers as well as code which is written across different files header files etc e Documentation Chapter 24 Dataflow Analysis based Virtual Function Analysis of ROSE tutorial pdf 10 3 Def use analysis If you want a def use analysis try this http www rosecompiler org ROSE_HTML_ Reference classVariableRenaming html VariableRenaming v project v run v getReachingDefsAtNode 2 http www rosecompiler org ROSE_Tutorial ROSE Tutorial pdf 3 http www rosecompiler org ROSE_Tutorial ROSE Tutorial pdf 43 Program Analysis 10 4 Pointer
237. s first then parallel body else if idx lt this gt get_clauses size 1 makeEdge this gt get_clauses idx 1 gt cfgForEnd CFGNode this idx result connect variables clauses first then parallel body else ROSE_ASSERT Bad index for SgOmpClauseBodyStatement return result step3 construct cfglutEdge for CFGNode For example std vector lt CFGEdge gt SgOmpClauseBodyStatement cfgOutEdges unsigned int idx edited by Hongyi for edges between SgUmpClauseBodyStatement and SgUmpClause std vector lt CFGEdge gt result addIncomingFortranGotos this idx result if idx this gt get_clauses size 1 makeEdge CFGNode this idx getNodeJustAfterInContainer this result J else if idx this gt get_clauses size makeEdge CFGNode this idx this gt get_body gt cfgForBeginning result connect variable clauses first parallel body last else if idx lt this gt get_clauses size connect variables clauses first parallel body last makeEdge CFGNode this idx this gt get_clauses idx gt cfgForBeginning result F else ROSE_ASSERT Bad index for SgOmpClauseBodyStatement return result 41 Program Analysis e 3 How to check the result First check AST graph Users ma23 Desktop Screen shot 2012 08 24 at 11 51 33 AM png In this e
238. s the FunctionState associated with the given function func may be any declared function static FunctionState getFuncState const Function amp func FunctionState fs new FunctionState func empty From FuntionState to NodeState aaa tallo UnstructuredPassInterAnalysis BR ea ea ak ea ak af aa af rar a ara k kkk kk IA void UnstructuredPassInterAnalysis runAnalysis set lt FunctionState gt allFuncs FunctionState getAllDefinedFuncs call a static function to get all function state s Go through functions one by one call an intra procedural analysis on each of them iterate over all functions with bodies for set lt FunctionState gt iterator it allFuncs begin it allFuncs end it FunctionState fState it intraAnalysis gt runAnalysis fState gt func amp fState gt state runs the intra procedural analysis on the given function returns true if the function s NodeState gets modified as a result and false otherwise state the function s NodeState bool UnstructuredPassIntraAnalysis runAnalysis const Function amp func 52 Lattices NodeState state DataflowNode funcCFGStart cfgUtils getFuncStartCFG func get_definition filter DataflowNode funcCFGEnd cfgUtils getFuncEndCFG func get_definition filter if analysisDebugLevel gt 2 Dbg dbg lt lt UnstructuredPassIntraAnalysis runAnalysis function lt lt func get_name g
239. s used in ROSE so they can have more focused learning experiences as C beginners Design Patterns ROSE uses some common design patterns e visitor pattern used to create the AST traversal 1 http en wikipedia org wiki Visitor 20pattern 197 26 Good API Design Google How to Design a Good API and Why it Matters by Joshua Bloch TODO convert from Markdown 26 1 Characteristics of a Good API e Easy to learn e Easy to use even without documentation e Hard to misuse Easy to read and maintain code that uses it e Sufficiently powerful to satisfy requirements e Easy to extend e Appropriate to audience 26 2 The Process of API Design e Gather true requirements in the form of use cases e Start with a short 1 page specification e Agility trumps completeness e Collect a lot of feedback e Use your API early and often e Test Driven Development TDD http en wikipedia org wiki Test driven_ development T he repetition of a very short development cycle first the developer writes a failing automated test case that defines a desired improvement or new function then produces code to pass that test and finally refactors the new code to acceptable standards e Doubles as examples tutorials and unit tests e Maintain realistic expectations e You won t be able to please everyone aim to displease everyone equally e Expect to evolve API mistakes happen real world usage is necessary 1 http lcsd0
240. setup cd modena build sh libtoolize force copy 1tdl automake aclocal I acmacros I acmacros ac archive I usr share aclocal autoconf automake a c configure ac 4 installing install sh configure ac 4 installing missing 3 Environment bootstrap source nfs apps python latest setup sh 4 Build and test mkdir buildTree cd buildTree configure with sqlalch emy HOME opt python sqlalchemy 0 7 5 1ib64 python2 4 site packages with target java interpreter java with target java compiler testTranslator with target java compiler flags ecj 1 6 with host java compiler flags source 1 6 22 4 Jenkins 22 4 1 Using External Benchmarks The way we set it up is to e In the benchmark we change the benchmark s build system to call the ROSE tool identityTranslator or your RTED tool installed e In the Jenkins test job e Build and install the tested ROSE prepare environment variables e Go to the benchmark with modified build system Build and run the benchmark Basically the test job should simulate how a ROSE tool would be used by end users not by tweaking ROSE for each different benchmarks 184 23 Git 23 1 Introduction The ROSE project has been through multiple stages of source content management starting from CVS then subversion and now Git Git becomes the official source code version control software due to its uniqu
241. sh python src totalview asymptote blender gcc hdf5 m4 mpich perl qt subversion upc autoconf doc git insure maple mpich2 pgi rdesktop swig visit automake doxygen gmp intel matlab mplayer psi ruby texinfo xemacs The root of most of these tools contains a setup sh file which you can source This will correctly setup your library path LD_LIBRARY_PATH and program path PATH GCC source nfs apps gcc 4 5 0 setup sh This GCC setup sh file should also source MPFR and GMP but if not please do it manually source nfs apps mpfr 3 0 0 setup sh source nfs apps gmp 4 3 2 setup sh If you fail to properly source these dependencies you may encounter this error nfs apps gcc 4 3 2 1libexec gcc x86_64 unknown linux gnu 4 3 2 f951 error while loading shared libraries libmpfr so 1 cannot open shared object file No such file or directory 86 15 Workflow 15 1 Motivation and Goals Quality comes from a good process The goal is to have a streamlined simplified and automated workflow involving both users and developers to e improve the qualify of ROSE source codes and documentations e improve our productivity optimize and simplify our daily work process so we can do more quality work using less time and other resources 15 2 Development Guide Developing a big sophisticated project entails many challenges To mitigate some of these challenges we have adopted several best practices incremental development co
242. sing e vim e emacs e KDevelop e Source Navigator e Eclipse e Netbeans The thing is that ROSE is huge and has some ridiculously large generated source file CxxGrammar h and CxxGrammar C are generated in the build tree for example So many code browsers may have trouble in handling ROSE 148 Portability 19 7 Portability 19 7 1 What is the status for supporting Windows We do maintain some preliminary Windows Support of building ROSE src to generate librose so by leveraging cmake However the work is not finished To build librose under windows type the following command lines in the top level source tree mkdir ROSE build cmake cd ROSE build cmake cmake DBOOST_ROOT ROSE_TEST_BOOST_PATH Example boost installation path opt boost_1_40_0 inst https mailman nersc gov pipermail rose public 2011 December 001349 html We have not finished the Windows work yet IT is on our list of things to do It was started and ROSE internally compiles using MS Visual Studio using project files generated from the Cmake build that we maintain and test within our release process for ROSE but does not pass our tests So it is not ready The distribution of the EDG binaries for Windows is another step that would come after that We don t know at present when this will be done it is important but not a high priority for our DOE specific work but important for other work The effort required is something that we c
243. specify one name it will use it as both the source and destination git push origin master 23 5 2 Delete remote branch Deleting a remote branch is simply a matter of specifying nothing as the lt source ref gt To delete the branch my branch issue this git push command git push origin refs heads my branch 23 6 Rebase It is recommended to rebase your branch before pushing your work So your local commits will be moved to the head of the latest master branch instead of being interleaved with commits from master git pull origin master git rebase master From http gitready com intermediate 2009 01 31 intro to rebase html Rebase helps to cut up commits and slice them into any way that you want them served up and placed exactly where you want them You can actually rewrite history with this command be it reordering commits squashing them into bigger ones or completely ignoring them if you so desire Why is this helpful e One of the most common use cases is that you ve been working on your own features fix es etc in separate branches Instead of creating ugly merge commits for every change that is brought back into the master branch you could create one big commit and let rebase handle attaching it e Another frequent use of rebase is to pull in changes from a project and keep your own modifications in line Usually by doing merges you ll end up with a history in which commits are interleaved between upstrea
244. st rose_enable_demo_project yes Since all configuration for the project is encapsulated in the rose config file renaming disabling or removing the project is trivial a project can be renamed simply by renaming its directory it can be disabled by renaming removing rose config or it can be removed by removing its directory The build and configure scripts should be rerun after any of these changes 172 How to add a new project directory Since projects are self encapsulated and optional parts of ROSE they need not be distributed with ROSE This enables end users to drop in their own private projects to an existing ROSE source tree without modifying any ROSE files and it allows ROSE developers to work on projects that are not distributed publicly Any project directory that is not part of ROSE s main Git repository will not be distributed this includes not distributing Git submodules although the submodule s placeholder empty directory will be distributed 20 9 3 Setting up Makefile am Each project should have at least one Makefile am each of which is processed by GNU automake and autoconf to generate a Makefile See documentation for automake for details about what these files should contain Some important variables and targets are e include top_srcdir config Makefile for ROSE includes and libs This brings in the definitions from the higher level Makefiles and is required by all projects It should b
245. st introduce something wrong and later correct it Here is an example translator to do the hack copy a defining function rename it fix its symbol include lt rose h gt include lt stdio h gt using namespace SageInterface int main int argc char argv SgProject project frontend argc argv AstTests runAllTests project Find a defining function named bar under project SgFunctionDeclaration func findDeclarationStatement lt SgFunctionDeclaration gt project bar NULL true ROSE_ASSERT func NULL Make a copy and set it to a new name SgFunctionDeclaration func_copy isSgFunctionDeclaration copyStatement func func_copy gt set_name bar_copy Insert it to a scope 145 Frequently Asked Questions FAQ SgGlobal glb getFirstGlobalScope project appendStatement func_copy glb if 1 fix up the missing symbol this should be optional now since Sagelnterface appendStatement should handle it transparently SgFunctionSymbol func_symbol glb gt lookup_function_symbol bar_copy func_copy gt get_type if func_symbol NULL func_symbol new SgFunctionSymbol func_copy glb gt insert_symbol bar_copy func_symbol endif AstTests runAllTests project backend project return 0 19 4 4 Can I transform code within a header file https mailman nersc gov pipermail rose public 2011 May 000971 html No ROSE does not u
246. ster 3 Push the central master branch to your Github s master branch bash 3 2 git push central central master refs heads master Total O delta 0 reused O delta 0 To git github 11nl gov lt user_oun gt rose git 16101fd 563b510 central master gt master 17 9 2 master cannot be synchronized In rare cases your repository s master branch cannot be automatically synchronized This is most likely due to merge conflicts You will receive an error message through an automated email resembling the following last updated on 7 24 2012 To gitCgithub 11n1 gov 1in32 rose git rejected origin master gt master non fast forward error failed to push some refs to gitOgithub 11n1 gov 1in32 rose git Your master branch at github 11n1 gov 1in32 rose git cannot be automatically updated with nfs casc overture ROSE git ROSE git master Please manually force the update 124 Past Software Experience Add the central repository as a remote call it nfs git remote add nfs nfs casc overture ROSE git ROSE git 1 First try to manually perform a merge in your local repository 1 Checkout and update your Github s master branch git checkout master git pull origin master 2 Merge the central master into your local master git pull nfs master lt no merge conflicts gt 3 Synchronize your local master to your Github s master git push origin HEAD refs head master 2 Otherwise try to resolve the confl
247. t calleeDef gt get_declaration gt get_args The number of actual arguments can be less than the number of formal arguments with implicit arguments or greater than the number of formal arguments with varargs 19 4 6 How to translate multiple files scattered in different directories of a project Expected behavior of a ROSE Translator A translator built using ROSE is designed to act like a compiler gcc g gfortran etc depending on the input file types So users of the translator only need to change the build system for the input files to use the translator instead of the original compiler On 07 25 2012 11 20 AM Fernando Rannou wrote gt gt Hello gt gt gt gt We are trying to use ROSE to refactor a big project consisting of gt gt several cc and hh files located at various directories Each gt gt class is defined in a hh file and implemented in a cc file gt gt Classes include include other class definitions But we have only gt found single file examples gt gt Is this possible If so how gt gt gt Thanks VOM MON N 19 5 Unparsing 19 5 1 Generate code into different files https mailman nersc gov pipermail rose public 2012 August 001742 html Question I wonder is it possible for ROSE to generate two files c and cl when it translates C to OpenCL Answer The ROSE outliner has an option to output the generated function into a new file ht
248. t section 4 to Preserve its Title section 1 will typically require changing the actual title 9 TERMINATION You may not copy modify sublicense or distribute the Document except as expressly provided under this License Any attempt otherwise to copy mod ify sublicense or distribute it is void and will automatically terminate your rights under this Li cense However if you cease all violation of this License then your license from a particular copyright holder is reinstated a provisionally unless and until the copyright holder explicitly and finally terminates your license and b permanently if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the ces tion Moreover your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reason able means this is the first time you have received notice of violation of this License for any work from that copyright holder and you cure the vi olation prior to 30 days after your receipt of the notice Termination of your rights under this section does not terminate the licenses of parties who have re ceived copies or rights from you under this License If your rights have been terminated and not perma nently reinstated receipt of a copy of some or all of the same material does not give you any rights to use it 10 FUTURE REVISIONS OF THIS LI
249. t message is a one line summary lt 50 words of the commit Start the summary with a topic enclosed in parentheses to indicate the project feature bugfix etc that this commit represents e Optional Use a bullet list using an asterisk for each item to elaborate on the commit Also see http spheredev org wiki Git_for_the_lazy Writing_good_commit_ messages 23 5 Push Creating and deleting branches on the remote repository is accomplished with git push This is its general form git push lt remote gt lt source ref gt lt destination ref gt e When you clone a repository the default lt remote gt is called origin e The lt source ref gt is the branch in your local repository cloned from lt remote gt that you want to create or synchronize with the lt remote gt e The lt destination ref gt is the branch that you want to create on the lt remote gt 23 5 1 Create remote branch Example git remote v 1 https github com rose compiler rose commit 801c53d81526e2eae7a68e0eabla9f 21b9892ab2 188 Rebase origin https github com rose compiler rose git fetch origin https github com rose compiler rose git push git branch master Method 1 git push origin master refs heads master Method 2 The currently checked out branch see git branch is also called the lt tt gt HEAD lt tt gt git push origin HEAD refs heads master Method 3 Git is pretty smart if you only
250. tent license to a party means to make such an agreement or commitment not to en force a patent against the party If you convey a covered work knowingly relying on a patent license and the Corresponding Source of the work is not available for anyone to copy free of charge and under the terms of this License through a publicly available network server or other readily accessible means then you must either 1 cause the Corresponding Source to be so available or 2 arrange to deprive yourself of the benefit of the patent license for this particular work or 3 arrange in a manner consistent with the re quirements of this License to extend the patent license to downstream recipients Knowingly re lying means you have actual knowledge that but for the patent license your conveying the covered work in a country or your recipient s use of the cov ered work in a country would infringe one or more identifiable patents in that country that you have reason to believe are valid If pursuant to or in connection with a single trans action or arrangement you convey or propagate by procuring conveyance of a covered work and grant a patent license to some of the parties re ceiving the covered work authorizing them to use propagate modify or convey a specific copy of the covered work then the patent license you grant is automatically extended to all recipients of the cov ered work and works based on it A patent license
251. th NOT line getLineLength The latter seems natural in the class declaration but proves superfluous in use as shown in the example The terms get and set must be used where an attribute is accessed directly e e g employee getName employee setName name matrix getElement 2 4 ma trix setElement 2 4 value The term compute can be used in methods where something is computed e e g valueSet gt computeAverage matrix gt computelnverse Give the reader the immediate clue that this is a potentially time consuming operation and if used repeatedly he might consider caching the result Consistent use of the term enhances readability The term find can be used in methods where something is looked up e e g vertex findNearest Vertex matrix findMinElement Give the reader the immediate clue that this is a simple look up method with a minimum of computations involved Consistent use of the term enhances readability The term initialize can be used where an object or a concept is established e e g printer initializeFontSet The american initialize should be preferred over the English initialise Abbreviation init should be avoided The prefix is should be used for boolean variables and methods e e g isSet isVisible isFinished isFound isOpen 101 Coding Standard There are a few alternatives to the is prefix that fit better in some situations These are the has can and should prefixes e
252. that x Vy z andx y w e Commutativity for all x y in L x V y y meet x x A y yAx e Associativity x V y Vz x V y V z similarly in the A operation e There are two unique elements of L called bottom _ _ and top T such that for all x xV_ _ _ andx AT T e Many lattices with some exceptions notably the lattice corresponding to constant propagatioin are also distributive x V y Az x Az V y Az Lattices and partial order xC y if and only ifany a A strictly ascending chain is a sequence of elements of a set X such that for x_i in X 2 1 2 n has the property L x Era n T The greatest is the chain with final index n such that n is the greatest such final index among all strictly ascending chains The height of a lattice is defined as the length of the longest strictly ascending chain it contains If a data flow analysis lattice has a finite height and a monotonic flow function then we know that the associated data flow analysis algorithm will terminate e Example If the greatest strictly ascending chain of a lattice L is finite and it takes finitely many steps to reach the top we can infer that the associated data flow algorithm terminates wikipedia used for definitions 24 5 Example Bit vector Lattices e The elements of the set are bit vectors e The bottom is the 0 vector e The top is a 1 vector e Meet is a bitwise And e Join is a bitwise Or BV denotes the
253. the code and had to go through the arduous task of understanding his own unreadable code Solution e Keep variable and function names meaningful Do full documentation as you go do not leave it for later 21 8 Think Before You Code Lesson e A developer wrote code without minding the structure This led to bloated and unreadable code that would have to be refactored several times Solution e A programmer must code AND design not just code Well structured code is much easier to read then badly structured code 21 9 Remember The User Lesson A developer wrote the code without knowing what the users actually needed This led to serious refactoring that could have been avoided or at least made simpler if he had concentrated on the user at all times Solution Whenever possible ask users for their input It will save you a lot of trouble in the long run 21 10 The User is Paramount Lesson A developer wrote a rather obtuse component without understanding exactly what the user might want this for 181 Lessons Learned Solution At the very least check that the input and output are what the user wanted this will save much time and aggravation 21 11 references http www projectsmart co uk lessons learned html 182 22 Testing ROSE uses Jenkins to implement a contiguous integration software development process It leverages a range of software packages to test its correctness robustness and performance
254. the virtual machine image oaoa a How was the virtual machine made How to create a new virtual image 2 CE on Drerequisites eo uns ar ee ede mh ee Ae identity Translator e e ea a a e aa Daa a aa AST dot graph generators nn call graph generator o oo ee Control flow graph generator a TODO am ww 10 10 11 12 15 15 15 17 17 17 18 18 18 18 19 21 21 22 23 25 25 25 26 28 28 28 III Contents 7 10 11 12 IV Supported Programming Languages i OpenMP as ass aa a Gos Br 1 28 SURG Asa a so Bos Mee la Pe 1 3 EUDA 2 3 2 np EA en een Bali A 2 7A OpenCL sein koe a an aan era De Abstract Syntax Tree Intermediate Representation 8 1 Sanity Check 64 20 2 me a war PH Bunde e 82 Visualization of AST 2 2 I on 83 Text Output ofan AST nn 8 4 Preprocessing Information 2 2 22 nn 85 AST Construction 2 2 2 2 onen Program Translation 9 1 Documentation 22 2 Cm m nn 9 2 Expected behavior of a ROSE Translator 9 3 SageBuilder and Sagelnterface 2 o nn nn 9 4 Steps for writing translators 2 2 CC nn nn 9 5 Order to traverse AST 2 2 2 2 LEE m nn ne 9 6 Example translators 2 22 Coon nn 9 7 Troubleshooting e e 2 22 rd erh en gs Program Analysis 10 1 control How graph hoi Be en Ram 10 2 Virtual Function Analysis 2 2 2 Common nn 10 3
255. the web page dump using a browser firefox index html How to read the trace file start from the beginning information is ordered based on the CFG nodes visited The order could be forward or backward order Check if the order is correct first then for each node visited Copying incoming Lattice 0 LiveVarsLattice liveVars b To outgoing Lattice 0 LiveVarsLattice liveVars Transferring the outgoing Lattice liveLat LiveVarsLattice liveVars b Dead Expression usedVars lt gt assignedVars lt gt assignedExprs lt gt usedVars 0 assignedExprs 0 Transferred outgoing Lattice 0 LiveVarsLattice liveVars b transferred modified 0 Propagating Merging the outgoing Lattice to all descendant nodes Descendants 1 Descendant 0x2b9e8c47f010 SglfStmt if flag 0 c a else c b Propagating to Next Node 0x2b9e8c47f010 SgIfStmt if flag 0 c a else c b Cur node Lattice 0 LiveVarsLattice liveVars b Next node Lattice 0 LiveVarsLattice liveVars a Next node s in data modified Adding Propagated Lattice 0 LiveVarsLattice liveVars a b propagated merged modified 1 A real example if flag c a else c b liveness analysis a b are live in two branches they are propagated backward to 74 How to debug Descendants 1 from c a back to if stmt next node Descendant Ox2ac8bb95c010 SgIfStmt if flag 0 c a else c b Propagating
256. the work 20 10 1 Reproduce the bug You can only fix a bug when you can reproduce it This step may be more difficult than it sounds In order to reproduce a bug you have to e find a proper input file e find a proper translator a translator shipped with ROSE is easy to find But be patient and sincere when you ask for a translator written by users e find a similar identical software and hardware environment a bug may only appear on a specific platform when a specific software configuration is used Possible results for this step e You can reproduce the bug reliably Bingo Go to the next step e You cannot reproduce the bug Either the bug report is invalid or you have to keep trying e You can reproduce the bug once a while random errors Oops This is kind of difficult situation 176 How to add a ROSE commandline option 20 10 2 Find causes of the bug Once you can reproduce the bug You have to identify the root cause of the bug using a debugger like gdb Common steps involved simplify the input code as much as possible It can be very hard to debug a problem with a huge input Always try to prepare the simplest possible code which can just trigger the bug e Often you have to use a binary search approach to narrow down the input code only use half of the input at a time to try Recursively cut the input file into two parts until no further cut is possible while you can still trigger the bug forw
257. tifiers etc should be enclosed in teletype lt tt gt lt pre gt The FooBar class can be found in the foobar cpp file e Source code should use a highlighted code block lt source lang lt language gt gt lt Code goes here gt lt source gt Enclosing code in a lt pre gt lt pre gt block is also okay but the highlighted code block is preferred e Headings The first word in a heading title should begin capitalized every other word should be in lowercase where applicable 1 3 Tracking Wiki Changes Learn how to Track Changes http en wikibooks org wiki Help Tracking_ changes 1 3 1 Enable Email Notifications for Changes to this book If you want to be notified of changes to this book WikiBooks provides email notifications for changes to Wiki pages that you explicitly choose to watch To use this feature 1 Create an account with WikiBooks http en wikibooks org w index php title Special UserLogin amp returnto MaintPage amp type signup 2 Login to WikiBooks and set your preferences top right corner of the web page for both email notifications and your watch list e Email notification settings e Preferences gt User profile gt E mail notifications gt E mail me when a page on my watchlist is changed check this on e Define your watchlist http en wikipedia org wiki Wikipedia Wikimedia_Commons Embedding Wikicommons 27_ media_in_Wikipedia_articles 4 http en wikibooks org wiki WATC
258. ting lt source lang cpp gt include lt iostream gt int main std cout lt lt Hello world n 207 Sandbox lt source gt 29 3 How to add comments which are only visible to editor not readers of a page Use the HTML comments for example the following comment will not show up in the paper rendered But it is visible to editor to reminder why things are done in certain way lt Please keep the pixel size to 400 so they are clean in the pdf version Thanks gt File Rose compiler code review 1 png thumb 400px Code review using github 11n1 gov 29 4 Syntax highlighting Copied from http en wikipedia org w index php title C 2B 2B action edit amp section 6 lt source lang cpp gt include lt iostream gt int main std cout lt lt Hello world n lt source gt Can generate the following highlighted code include lt iostream gt int main std cout lt lt Hello world n 29 5 Math formula You can pretend to edit this section to see how math formula are written More resources are at e http en wikipedia org wiki Help Formula e http www mediawiki org wiki Manual Math 208 Math formula loga n logg n logg n 1 loga n 2 logy 1 log n log n loga n logs n nloga n logo n 1log2 n log2 n 1 loga n 2 log2 1 lt logs n loga n logs n log2 n nlog
259. tityTranslator performs some modifications automatically These modifications are e Expanding the assert macro e Adding extra brackets around constants of typedef types e is translated in the output to c Typedef_Example 12 e Converting NULL to 0 g c Typedef_Example 12 How can I avoid these modifications Answer No There is no easy way to avoid these changes currently Some of them are introduced by the cpp preprocessor Others are introduced by the EDG front end ROSE uses 100 faithful source to source translation may require significant changes to preprocessing directive handling and the EDG internals We have had some internal discussion to save raw token strings into AST and use them to get faithful unparsed code But this effort is still at its initial stage as far as I know 19 4 2 How to build a tool inserting function calls https mailman nersc gov pipermail rose public 2010 July 000319 html Question I am trying to build a tool which insert one or more function calls whenever in the source code there is a function belonging to a certain group e g all functions beginning with foo_ During the ast traversal how can I find the right place i e there is a function in ROSE that searches for a string pattern or something similar Answers e In Chapter 28 AST Construction of the ROSE tutorial there are examples to instrument function calls into the AST using traversals or a queryTree I would appr
260. to Next Node Ox2ac8bb95c010 SgIfStmt if flag 0 c a else c b Cur node Lattice 0 LiveVarsLattice liveVars a current node s lattice Next node Lattice 0 LiveVarsLattice liveVars next node s lattice before propagation Next node s in data modified Adding Propagated Lattice 0 LiveVarsLattice liveVars a propagate a into if stmt s lattice propagated modified 1 Descendants 1 from c b gt if stmt Descendant Ox2ac8bb95c010 SgIfStmt if flag 0 c a else c b Propagating to Next Node Ox2ac8bb95c010 SgIfStmt if flag 0 c a else c b Cur node Lattice 0 LiveVarsLattice liveVars b Next node Lattice 0 LiveVarsLattice liveVars a Next node s in data modified Adding Propagated Lattice 0 LiveVarsLattice liveVars a b now both a and b are propagated merged propagated modified 1 11 11 2 Dump cfg dot graph with lattices A class analysisStatesToDot is provided generate a CFG dot graph with lattices information AnalysisDebuggingUtils C class analysisStatesToDOT public UnstructuredPassIntraAnalysis 1 private LiveDeadVarsAnalysis lda reference to the source analysis Analysis lda reference to the source analysis void printEdge const DataflowEdge amp e print data flow edge void printNode const DataflowNode amp n std string state_string print date flow node void visit const Function amp func const DataflowNode amp
261. to the effect of iterator invalidation e please use post order or reverse order of pre order for your traversal hooked up with translation 20 3 4 Searching for the AST node There are multiple ways to find things you want to translate in AST 158 How to create a translator AST Query e Via AST Query Node query returns a list of AST nodes in the same type This is often enough to simple translations Rose_STL_Container lt SgNode gt ProgramHeaderStatementList NodeQuery querySubTree project V_SgProgramHeaderStatement for Rose_STL_Container lt SgNode gt iterator i ProgramHeaderStatementList begin i ProgramHeaderStatementList end i SgProgramHeaderStatement ProgramHeaderStatement isSgProgramHeaderStatement i More information about AST Query can be found at 6 Query Library of the ROSE User Manual pdf AST Traversal e Through AST traversal walks through whole AST using different orders pre order or post order Post order traversal is recommended to avoid modifying things the traversal will hit later on similar problem as iterator invalidation in C e The AST traversal gives visit functions to hook up your translation functions A switch statement is can be used for handling different types of AST node class f2cTraversal public AstSimpleProcessing public virtual void visit SgNode n 33 void f2cTraversal visit SgNode n switch n gt variantT case V_SgSour
262. tps github com rose compiler rose blob master src midend programTransformation astOutlining Dutliner hh Generate the outlined function into a separated new source file rose outline new_file extern bool useNewFile 147 Frequently Asked Questions FAQ You may want to check how this option is used in the outliner source files to get what you want 19 6 Daily work 19 6 1 git clone returns error SSL certificate problem Symptom git clone https github com rose compiler rose git Cloning into rose error SSL certificate problem verify that the CA cert is OK Details error 14090086 SSL routines SSL3_GET_SERVER_CERTIFICATE certificate verify failed while accessing https github com rose compiler rose git info refs fatal HTTP request failed The reason may be that you are behind a firewall which tweaks the original SSL certification Solutions Tell cURL to not check for SSL certificates Solution 1 Environment variable temporary env GIT_SSL_NO_VERIFY true git pull Solution 2 git config permanent set local configuration git config local http sslVerify false Solution 2 set global configuration git config global http sslVerify false 19 6 2 What is the best IDE for ROSE developers https mailman nersc gov pipermail rose public 2010 April 000115 html There may not be a widely recognized best integrated development environment But developers have reported that they are u
263. ual integration is not performed This typically occurs when one of your jobs have a system failure for instance so it has to be manually re started If you see that all of your jobs have passed but your work has not been integrated please let the Jenkins administrator know 18 6 Frequently Failed Jobs See details at ROSE Compiler Framework Jenkins Failures 2 http en wikibooks org wiki ROSE 20Compiler 20Framework 2FJenkins 20Failures 129 Continuous Integration 18 7 Connection to Code Review Github IInl gov 2 Auto regression tests Rose compiler rose liao6 rose Branches Branches Master gt Master Jenkins nsf casc rose Branches e Master e cl review rc 4 auto push master ME 1 auto pull master liao6 has cl review rc branch Figure 5 Connection between Github Enterprise and Jenkins In reality most LLNL developers are now asked to push things to Github Enterprise for code review first instead of directly pushing to our central git repository The synchronization between the Github Enterprise s code review repositories and our Central Git repo are automated 18 7 1 Auto Pull Auto pull we have another Jenkins at https hudson rose 30 8443 jenkins which serves as the bridge between Github Enterprise and our main production Jenkins e For each private repositories on Github Enterprise we have a Jenkins job to monitor the master branch for app
264. uild option then autoconf can directly find the detail platform type Users ma23 ROSE configure with CXX_DEBUG ggdb3 with CXX_WARNINGS Wall with boost Users ma23 Desktop ROSE boost BOOST_INSTALL with gfortran Users ma23 Desktop macports bin gfortran mp 4 4 with alternate_backend_fortran_compiler gfortran mp 4 4 GFORTRAN_PATH Users ma23 Desktop macports bin gfortran mp 4 4 build x86_64 apple darwin10 At last make Thanks Regards 4 http sources redhat com autobook autobook autobook_266 html 5 http sources redhat com autobook autobook autobook_261 html SEC261 19 Installation Hongyi Ma 20 5 Virtual machine image The goal of this page is to document e How users can download the virtual machine image or virtual appliance and use ROSE out of box e how the virtual machine image for a fully installed ROSE is created 5 1 How to use the virtual machine image 5 1 1 Obtain the Virtual Machine Image Download the virtual machine image created by using VMware Player e http www rosecompiler org Ubuntu ROSE Demo tar gz e Warning it is a huge file of 4 8 GB e Demonstration user account sudo user in Ubuntu e account demo e password password Warning LLNL users may not be able to download it due to limitations to max downloaded file size within LLNL It may also be against LLNL s security policy to run a virtual machine without authorization So this image should not be used inside
265. ule src frontend CxxFrontend EDG path src frontend CxxFrontend EDG url ROSE EDG git url lt path to your ROSE EDG git gt submodule projects vulnerabilitySeeding path projects vulnerabilitySeeding url vulnerabilitySeeding git Run git submodule commands cd ROSE git submodule init git submodule update The commands above will check out a version of the EDG submodule and save it into ROSE src frontend CxxFrontend EDG 2 http www kernel org pub software scm git docs git submodule html 11 Obtaining ROSE 3 4 2 As a Drop in b As a Drop in Move ROSE EDG tarball into its correct location within the ROSE source tree ROSE src frontend EDG tar xzvf ROSE EDG b12158aa2 tgz 1s EDG ROSE EDG b12158aa2 tgz mv EDG ROSE src frontend EDG Warning This method may not work because EDG is a submodule of ROSE and therefore requires a version synchronization between the two For example the latest version of ROSE may not use the latest version of ROSE s EDG 3 4 3 The remaining steps 4 In ROSE run the ROSE build script from the top level of the ROSE source tree i e ROSE This script bootstraps Autotools including the Makefile ams in the EDG source tree 5 Configure and build ROSE Normally during this process ROSE would attempt to download an EDG binary tarball for you but since you have the source code this step will be skipped 3 5 EDG tarball 3 5 1 Proc
266. ults Algorithm complex compiler algorithms are often just enhanced versions of more fundamental algorithms Implement the fundamental algorithms first to gain insight and experience Then afterward you can implement the full blown versions Language for projects dealing with multiple languages focus on one language at a time Platform limit the scope of supported platforms Linux Ubuntu OS X TODO add reference to ROSE supported platforms Performance Start with a basic working implementation first Then try to optimize its performance efficiency Scope your translator could first focus on working at a function scope then grow to handle an entire source file or even multiple files at the same time Skeleton then meat a project should be created with the major components defined first Each component can be enriched separately later on Annotations manual vs automated Performing one compiler task often requires results from many other tasks being developed Defining source code annotations as the interface between two tasks can decouple these dependencies in a clean manner The annotations can be first manually inserted Later the annotations can be automatically generated by the finished analysis Optional vs Default introducing a flag to turn on off your feature Make it as a default option when it matures 157 How tos 20 3 How to create a translator Translator basically converts one AST to another version of
267. und an IR node with preprocessing Info attached memory address 0x2b7e1852c7d0 Sage type SgFunctionDeclaration in file export tmp liao6 workspace userSupport main cxx line 3 column 1 AS PreprocessingInfo 0 classification Geren ON String format include all_headers h relative position is before 142 AST 19 3 5 SgClassDeclaration get_ definition returns NULL If you look at the whole AST graph carefully you can find defining and non defining declarations for the same class A symbol is usually associated with a non defining declaration A class definition is associated with a defining declaration You may want to get the defining declaration from the non defining declaration before you try to grab the definition 19 3 6 How to add new AST nodes There is a section named 1 7 Adding New SAGE III IR Nodes Developers Only in ROSE Developer s Guide http www rosecompiler org ROSE_DeveloperInstructions pdf But before you decide adding new nodes you may consider if AstAttribute user defined objects attached to AST would be sufficient for your problem For example the ist version of the OpenMP implementation in ROSE rose projects OpenMP_ Translator started by using AstAttribute to represent in formation parsed from pragmas Only in the 2nd version we introduced dedicated AST nodes There are two separate steps when new kinds of IR nodes are added into ROSE e First step declarat
268. ur desk office accessible to others Physically isolated office desk may have very negative impact on your productivity e Installing ROSE being able to smoothly configure compile and install ROSE e Build system being able to add a project first skeleton into ROSE by modifying Makefile am etc 84 Termination checklist Contribution following ROSE Coding Standard and passing code review e Documentation sufficient documentation about what you work is about e Software Engineering e Style guidelines Doxygen comments naming conventions where to put things etc e Interface Does the code has a clean and simple interface to be used by users Algorithm design documented by source comments how things are expected to work e Coding implementation correctly implement the designed algorithm e Tests Each contribution must have the accompanying tests to make sure it works as expected Continuous integration push commits to be code reviewed and tested by Jenkins every two or three weeks for your incremental development results e Add a new test job if none of the existing ones tests your project Confirm your commits are merged into the ROSE project s central master branch github com provides graphs for individual impact e https github com rose compiler rose commits author author_email_here 14 4 Termination checklist We often have interns collaborators subcontractors finishing up their official duties with us Here a brief check
269. ve if you have been forced to endure an unfortunate experience like this don t let it sour you to the whole point and value of coding standards It doesn t take a very large organization to find there is value in having consistency since different programmers can edit the same code without constantly reorganizing each others code in a tug of war over the best coding standard 16 1 3 Must Should and Can The terms must should and can have special meaning e A must requirement must be followed e A should is a strong recommendation e A can is a general guideline 16 1 4 Got New Ideas Suggestions This is not a place to write down the new ideas concepts suggestions to be used in the future If you have suggestions put into the discussion tab link of this page We do welcome suggestions for improvements and changes so we can do things faster and better e For suggestions please follow the procedure defined in Proposing_Workflow_ Changes e The suggestions will be reviewed by the criteria defined in Reviewing Workflow_ Change Proposals 2 http en wikibooks org wiki Talk ROSE_Compiler_Framework Coding_Standard 3 Chapter 15 4 on page 89 4 Chapter 15 5 on page 90 92 Git Convention 16 2 Git Convention 16 2 1 Name and Email Before you commit your local changes you MUST ensure that you have correctly configured your author and email information on all of your machines Having a recognizable and consistent name
270. vered work is covered by this License only if the output given its content con stitutes a covered work This License acknowledges your rights of fair use or other equivalent as pro vided by copyright law You may make run and propagate covered works that you do not convey without conditions so long as your license otherwise remains in force You may convey covered works to others for the sole purpose of having them make modifications exclusively for you or provide you with facilities for running those works provided that you comply with the terms of this License in conveying all material for which you do not control copyright Those thus making or running the covered works for you must do so exclu sively on your behalf under your direction and con trol on terms that prohibit them from making any copies of your copyrighted material outside their relationship with you Conveying under any other circumstances is permit ted solely under the conditions stated below Subli censing is not allowed section 10 makes it unneces sary 3 Protecting Users Legal Rights From Anti Circumvention Law No covered work shall be deemed part of an effec tive technological measure under any applicable law fulfilling obligations under article 11 of the WIPO copyright treaty adopted on 20 December 1996 or similar laws prohibiting or restricting circumven tion of such measures When you convey a covered work you waive any legal power t
271. view Process Github IInI gov 2 Add reviewers as collaborators liao6 rose Branches Master Bugfix FeatureX git push to non master only local rose 8 Review fails 4 Local edits commits 8 Pass merge Rose compiler rose A by reviewer Branches Master 7 Pull merge request e change src gt dest base bug feature branch gt master Figure 2 Code review using github llnl gov 115 Code Review Process Github lInl gov 2 Auto regression tests Rose compiler rose liao6 rose Branches Branches e Master gt Master Jenkins nsf casc rose Branches Master e cl review rc 4 auto push master 1 auto pull master liao6 has cl review rc branch Figure 3 Connection between github and Jenkins 17 1 Motivation Without code review developers have e added unreadable contributions which do not conform to any consistent coding styles e added undocumented contributions which cannot be understood by anybody else essentially useless contributions e added untested contributions codes without accompanying tests so the contributions do not work as expected or can be easily broken by other conflicting contributions another essentially less useful contributions e disabled tests to subvert our stringent Jenkins CI regression tests e added files into wrong directories with improper names e committed hundreds of r
272. w to add content of your new how to page e you can now add new content and save it e Again each how to wiki page should NOT contain any level one or level two heading so it can be included at the correct levels in the print version of this wikibook 153 How tos 20 1 4 Insert image to wiki page e To use your own image in wiki page you have to upload the image to http commons wikimedia org e Once you upload the image it will become public to all wikibooks users Be sure to declare your copyright if the image is created by yourself e Following this instruction to insert image and adjust the layout of your page http en wikibooks org wiki Using Wikibooks Inserting Images 20 1 5 Rules of the content e Only level three headings and higher are allowed in a how to page This is necessary for the how to page to be correctly included into the final one page print version of this wikibook Sorry about this restriction e Again please don t use level one or level two headings in a how to page e Keep each how to short and focused Readers are expected to only spend 30 minutes or much less to quickly learn how to do something using ROSE e After you created a new how to page and saved your contributions Please go to the print version to make sure it shows up correctly e Here is the link http en wikibooks org wiki ROSE_Compiler_Framework Print_version e Having new content show up in the print version
273. xample you will find that there are three subtree from SgOmpParallelStatement One is get_ body the other two are SgOmpPrivateClasue and SgOmpSharedClauserespectively So the index is 3 the order to visit CFGNode is to visit clauses first then parallel body Ox10Sfbe110 y lt SgBasicBlock gt line 11 idx 7 Mi SgOmpParallelStatement lt SgOmpParallelStatement gt line 20 idx 0 vateClause lt SgOmpPrivateClause gt line 0 idx 0 3 var ref of a lt SgVarRefExp gt line 0 idx 0 vateClause lt SgOmpPrivateClause gt line 0 idx R e FF e var_rel lt SgVarRefExp gt line 0 idx 0 t SgOmpPrivateClause lt SgOmpPrivateClause gt line 0 idx t SgOmpParallelStatement lt SgOmpParallelStatement gt line 20 idx 1 SgOmpSharedClause lt SgOmpSharedClause gt line 0 idx 0 var_ref_of_pp lt SgVarRefExp gt line 0 idx 0 SgOmpSharedClause lt SgOmpSharedClause gt line 0 idx s H Hl S lelStatement lt SgOmpParallelStatement gt line 20 idx 2 0x105fbc220 lt SgBasicBlock gt line 21 idx 0 Figure 1 Add caption here 42 Virtual Function Analysis 10 1 2 Static Control Flow Graph Due to the performance concern of virtual control flow graph we developed another static version which persistently exists in memory like a regular graph Facts e Documentation 19 7 Static CFG of ROSE tutorial pdf e Test Directory rose tests CompileTests staticCFG_ test
274. y as fit reasonably on the actual cover and continue the rest onto adjacent pages If you publish or distribute Opaque copies of the Document numbering more than 100 you must ei ther include a machine readable Transparent copy along with each Opaque copy or state in or with each Opaque copy a computer network location from which the general network using public has access to download using public standard network protocols a complete Transparent copy of the Doc ument free of added material If you use the lat ter option you must take reasonably prudent steps when you begin distribution of Opaque copies in quantity to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy directly or through your agents or retailers of that edition to the public It is requested but not required that you con tact the authors of the Document well before redis tributing any large number of copies to give them a chance to provide you with an updated version of the Document 4 MODIFICATIONS You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above provided that you release the Modi fied Version under precisely this License with the Modified Version filling the role of the Document thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it
275. your page http en wikibooks org wiki Using_Wikibooks Inserting Images 20 1 3 Rules of the content e Only level three headings and higher are allowed in a how to page This is necessary for the how to page to be correctly included into the final one page print version of this wikibook Sorry about this restriction e Again please don t use level one or level two headings in a how to page e Keep each how to short and focused Readers are expected to only spend 30 minutes or much less to quickly learn how to do something using ROSE e After you created a new how to page and saved your contributions Please go to the print version to make sure it shows up correctly e Here is the link http en wikibooks org wiki ROSE_Compiler_Framework Print_version e Having new content show up in the print version will make sure it is really visible and consistent with the rest of the book please specify the how to topic is the current practice or the proposed new ways of doing things So we can have clear guideline for code review for what is mandatory and what is optional e rename three places of the pasted text with the desired page name for example ROSE Compiler Framework How to do XYZ How to do XYZ dhunparserurl ROSE Compiler Framework How to do XYZ e click save page e You will see red text trying to link to the not yet existing How to do XYZ page e click any of the red text it will bring you to an editing windo
276. ything to invoke the analysis Right now you need to go over each function definition and invoke the analysis explicitly as illustrated by the main function in the file gt 3 Say I want to query whether two pointer variables alias and I have gt SGNodes to their declarations How do I get the AstNodePtr needed to gt invoke the may_alias AstInterface amp const AstNodePtr amp const gt AstNodePtr amp function Or maybe I should rather invoke the version of gt may_alias that takes two strings varnames To convert a SgNode x to AstNodePtr wrap it inside an 44 SSA AstNodePtrImpl object i e do AstNodePtrImpl x as illustrated inside the operator of TestPtrAnal in steensgaardTest2 C gt 4 How do I query whether two parameters alias The PtrAnal class has the following interface method may_alias AstInterface amp fa const AstNodePtr amp r1 const AstNodePtr amp r2 It is implemented in SteensgaardPtrAnal class which inherit PtrAnal class To build AstInterface and AstNodePtr you simply need to wrap SgNode with some wrapper classes illustrated by steensgaardTest2 C Qing Yi void func void int pointer int aliasPointer pointer malloc sizeof int aliasPointer pointer aliasPointer 42 printf d n pointer The SteensgaardPtrAnal output function returns sizeof int LOC1 gt L0C2 42 LOC3 gt LOC4 func LOC5 gt LOC6 inparams gt outp

ROSE Compiler Framework

Contents

Download Pdf Manuals

Related Search

Related Contents