# ROSE Compiler Framework/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.

## 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:
* rename three places of the pasted text with the desired page name, for example
* 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.
** 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.

### Insert image to wiki page

* To use your own image in wiki page, you have to upload the image to http://commons.wikimedia.org/.
* 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.
* Following this instruction to insert image and adjust the layout of your page: http://en.wikibooks.org/wiki/Using_Wikibooks/Inserting_Images

### Rules of the content

* 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.
** 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.
** Here is the link: http://en.wikibooks.org/wiki/ROSE_Compiler_Framework/Print_version
** 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.

## 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 results.
* 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.

## How to visualize AST
### Overview

Three things are needed to visualize ROSE AST:
* Sample input code: you provide it
* a dot graph generator to generate a dot file from AST: ROSE provides dot graph generators
* a visualization tool to open the dot graph: ZGRViewer and Graphviz are used by ROSE developers
If you don't want to install ROSE+ZGRview + Graphvis from scratch, you can directly use ROSE virtual machine image, which has everything you need installed and configured so you can just visualize your sample code.

### Sample input code

Please prepare simplest input code without including any headers so you can get a small enough AST to digest.

### Dot Graph Generator

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.
Tools to generate AST graph in dot format. There are two versions
* dotGenerator: simple AST graph generator showing essential nodes and edges
* dotGeneratorWholeASTGraph: whole AST graph showing more details. It provides filter options to show/hide certain AST information.
command line:
To skip builtin functions
* dotGeneratorWholeASTGraph -DSKIP_ROSE_BUILTIN_DECLARATIONS yourcode.c

### Dot Graph Visualization

To visualize the generated dot graph, you have to install
* Graphviz: http://www.graphviz.org/Download.php .
* ZGRViewer: http://zvtm.sourceforge.net/zgrviewer.html#download. (Version 0.8.x is recommended since 0.9.x has a bugs like inversed (reversed) direction to drag a graph around.)
Please note that you have to configure ZGRViewer to have correct paths to some commands it uses. You can do it from its configuration/setting menu item. Or directly modify the text configuration file (.zgrviewer).
One example configuration is shown below (cat .zgrviewer)
You have to configure the run.sh script to have correct path also
cat run.sh

### Example session

A complete example

### example output

We put some example source files and their AST dump files into: https://github.com/chunhualiao/rose-ast
* for example: https://github.com/chunhualiao/rose-ast/blob/master/func1.c_WholeAST.dot.png
* https://github.com/chunhualiao/rose-ast/blob/master/parallelfor.c_WholeAST.dot.png

### Print AST as horizontal tree

SageInterface functions
A translator (textASTGenerator) is also available, with its source code under exampleTranslators/defaultTranslator .
* make install-tools will install this tool
* textASTGenerator input.c will generate a text output of the entire AST

#### Example use inside of gdb

* to print a portion of AST to the screen
* to print a portion of AST into a text file

#### textASTGenerator

Example command line use:
textASTGenerator -c test_qualifiedName.cpp
cat test_qualifiedName.cpp.AST.txt

### Render the AST in HTML

The repo errington1/ast-to-html contains a tool for rendering the Rose abstract syntax "graph" as collapsible HTML with shared nodes and cycles represented by HTML links. For now, it's available only from the command line. The plan is to add command-line options to omit parts of the tree and to make the tool available as a library. For now, it somewhat arbitrarily omit portions of the tree that originate from the file rose_edg_required_macros_and_functions.h.
The command:
will produce file.C.html which can be viewed with a browser:

## How to create a translator

Translator basically converts one AST to another version of AST. The translation process may add, delete, or modify the information stored in AST.

### Overview

A ROSE-based translator usually has the following steps
* Search for the AST nodes you want to translate.
* Perform the translation action on the found AST nodes. This action can be one of two major variants
      * Updating the existing AST nodes
      * 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 SageInterface functions.
      * 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.
      * Optionally update other related information for the translation.

### 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.
More details for visualize AST are available at How to visualize AST.

### Design considerations

It is usually a good idea to
* separate the searching step from the translation step so one search (traversal) can be reused by all sorts of translations.
* When design the order of searching and translation, be careful about if the translation will negatively impact on the searching
** Please void pre-order traversal since you may end up modifying AST nodes to be visited later on, similar to the effect of iterator invalidation.
** please use post-order, or reverse order of pre-order for your traversal hooked up with translation

### Searching for the AST node

There are multiple ways to find things you want to translate in AST.

#### AST Query

* Via AST Query: Node query returns a list of AST nodes in the same type. This is often enough to simple translations
More information about AST Query can be found at "6 Query Library" of the ROSE User Manual pdf.

#### AST Traversal

* 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++)
** 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.
More information about AST Traversal can be found at "7 AST Traversal" of the ROSE User manual pdf online.

### Performing Translation

Before you write your translator, please read Chapter 32 AST Construction of ROSE tutorial pdf documentation (http://rosecompiler.org/ROSE_Tutorial/ROSE-Tutorial.pdf). It contains essential information for any translation writers.
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
* void translateForLoop(SgForLoop* n)
* void translateFileName(SgFile* n)
* void translateReturnStatement(SgReturnStmt* n), and so on
Other tips
* Reference ROSE doxygen website for information of each AST node: http://rosecompiler.org/ROSE_HTML_Reference/index.html
* 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.
* Look up in SageInterface Namespace (http://rosecompiler.org/ROSE_HTML_Reference/namespaceSageInterface.html) for the translation functions you need. If there is none, then write your own function.
* Besides building things from scratch, you can use SageInterface::deepCopy to copy AST subtree.
* Update the information, or create the new AST node you need.
* Replace the existing AST node with your updated or new AST node.

##### Updating Tree

* You might need to handle some details, like removing symbol, updating parent, and symbol table.
* Be careful to use deepDelete and deepCopy. Some information might not be updated properly. For example, deepDelete might not update your symbol table.

### Verify the correctness

You can use wholeAST graph to verify your translation.
All ROSE-based translators should call AstTests::runAllTests(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

## Sample translators

Here we list a few sample translators which can grow to more sophisticated ones you want.

### Find pragmas

Here is an example project doing pragma parsing and saving the results into AST attributes.
https://github.com/rose-compiler/rose-develop/tree/master/projects/pragmaParsing

### Loop transformation

SageInterface namespace (http://rosecompiler.org/ROSE_HTML_Reference/namespaceSageInterface.html) has many translation functions, such as those for loops.
For example, there is a loop tiling function defined in https://github.com/rose-compiler/rose/blob/master/src/frontend/SageIII/sageInterface/sageInterface.C :
An example Test translator is provided to test this function:
* https://github.com/rose-compiler/rose/blob/master/tests/roseTests/astInterfaceTests/loopTiling.C
And it has a test input file:
* https://github.com/rose-compiler/rose/blob/master/tests/roseTests/astInterfaceTests/inputloopTiling.C

## How to build your translator

See How to set up the makefile for a translator

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

### Change the sourcefile information

   * change the output file name. The suffix name has to be changed with this following function.
   * change the output language type.
   * Set the output to be target-language only.

### 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.
    C SgForStatement
    Fortran uses SgFortranDo for the do loops.
    Fortran SgFortranDo

### Implement the translation functions

   * Use the wholeAST as reference to implement the translation function.
   * Generate the new AST node by copy required information from the original AST node.
   * Remove the original node, and make sure the parent/child relationship in AST is setup properly.

### Testing output code

   * If compiler is available to test the output code, run the backend to generate object by the backend compiler.
   * 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.

## 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 Framework/Installation.

### Environment variables

You must have the proper environment variable set so you translator can find the librose.so during execution.

### Translator Code

Here is a simplest ROSE translator.

### Example 1

If you have a project that's separate from ROSE (i.e., you compile it with an *installed* version of ROSE) it's up to you how to do things.
If the project depends only on ROSE and ROSE's dependencies then you can use the Makefile described at the end of the ROSE installation instructions http://rosecompiler.org/ROSE_HTML_Reference/installation.html

### Complete examples

There are project examples demonstrating different ways of building your projects using ROSE's headers/libraries.
They are available at: https://github.com/chunhualiao/rose-project-templates
A few templates for independent projects using ROSE. By independent, we mean the projects are located outside of ROSE's source tree.
* template-project-v1 : using Makefile to build the project
* template-project-v2 : using Makefile to build and run a ROSE plugin

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

## Preparations

First and foremost, make sure your ROSE installation and your translator was built with -g and without GCC optimizations turned on. This will ensure all debug information will be best preserved.
To configure ROSE installation with debugging options, you can add the following options to your normal configuration.
If you already built ROSE but forgot what options you used, you can go to your buildtree of ROSE to double check if debugging options are used:
Before you debug your own translators, you may want to doublecheck if ROSE's builtin translator (rose-compiler) can handle your input code properly. If not, you should report the bug to the ROSE team.
If rose-compiler can handle it but your customized translator cannot. The problem may be caused by the customizations you introduced in your translators.
Another thing is to reduce your input code to be as small as possible so it can just trigger the error you are interested in. This will simplify the bug hunting process dramatically. It is very difficult to debug a translator processing thousands of lines of code.

## Basics of GDB

gdb is a debugger. It provides a controlled execution environment for you to inspect if your program is running the way you expected.
Essentially, it allows you to:
* run your program within a controlled debugging environment: using gdb—args <program> <args...>
** or libtool—mode=execute gdb—args <progra> <args...> for libtool built executables.
* stop at desired execution points
** normal breakpoints (called breakpoints): using break <where>, <where> can be a function name, line_number, or file:line_number.
** when value changes for a given variable(called watchpoint): using watch <where>
** segmentation fault : this will happen automatically, so you can inspect how a seg fault happens
** assertion failure: this will happen automatically, so you can debug assertion failures.
* inspect and even change things like variables, types, etc. once your program stops at desired execution points
** inspect the call stack at the breakpoint: using backtrace or bt in short. frame <frame#> to go to the stack frame of your interests.
** look around relevant source code near the breakpoint: using list [+|-|filename:linenumber|filename:function]
** inspect the values of variables and expressions: using print <what>, <what> can be any variable, expression, or even function call.
** inspect the type of a variable: whatis variable_name
** change the content of a variable to a given value: set <var_name>=<value>
** call functions: using print function_name, this is helpful to call some dump functions for some class objects.
* control the execution further
** step one statement at a time, through the execution of your program: you can step through at the current frame (next), step down into a frame (step), or step out the current stack frame (finish),
** continue the execution until next breakpoint or watchpoint: using continue or c in short
** return from a function immediately, passing a given value: return <expression>
* and other things.
For a quick overview, you can look through a cheat sheet online:
* https://kapeli.com/cheat_sheets/GDB.docset/Contents/Resources/Documents/index
From Rob, There is a curses-based wrapper called "cgdb" .
* You get a split window: the bottom is the GDB console and the top is syntax-highlighted source code that automatically tracks your current location and supports PageUp/PageDn, which is a lot easier to use than GDB's "list" command.
* it requires ncurses-devl and readline-devel to install.

## A translator not built by ROSE's build system

This is also called out-of-sourcetree build for some people.
If the translator is built using a makefile without using libtool. The debugging steps of your translator are just classic steps to use gdb.
* 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 breakpoint
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

### Example 1: debugging an AST traversal

We first prepare the example ROSE-based analyzer traversing AST to find loops. Rename it to be demo.C:
* wget https://raw.githubusercontent.com/rose-compiler/rose/develop/tutorial/visitorTraversal.C
* mv visitorTraversal.C demo.C
We can look into the example analyzer's source code: cat demo.C Essentially, we can see the following content:
A ROSE-based tool initializes ROSE first (at line 35). Then the frontend function is called to parse an iput code and generate an AST rooted at project of SgProject type (at line 40).
After that, a traversal object is declared at line 44. The object is used to traverse the input files of the project, using a preorder traversal.
The traversal object is based on a derived visitorTraversal class at line 6. This derived class has member functions to define what should happen during construction (line 14), visiting a node (line 18), and the end of the traversal (line 26).
Now get a sample makefile to build the source file into an executable file:
* wget https://raw.githubusercontent.com/rose-compiler/rose/develop/tutorial/SampleMakefile
The makefile should be self-explanatory. It uses rose-config in the installation path to set various environment variables for compilers, compilation and linking flags, library path, etc.
Get an example input code for the analyzer:
* wget https://raw.githubusercontent.com/rose-compiler/rose/develop/tutorial/inputCode_ExampleTraversals.C
The input code has two for-loops at line 20 and 41, as shown at link
Prepare the environment variable used to specify where ROSE is installed.
* export ROSE_HOME=/home/freecc/install/rose_install
Build the analyzer:
* make -f SampleMakefile
There should be an executable file named demo under the current directory:
Finally, run the demo analyzer to process the example input code:
* ./demo -c inputCode_ExampleTraversals.C
The analyzer should find two for loops and report the end of the traveral.

#### Debug The Translator

Now let's debug this simple translator.
First of all, use gdb -args to run the translator with options

#### Inspect post_construction_intialization

Breakpoints at the post_construction_initialization are useful to inspect when a node is created and/or if a node has required fields set after construction. For example, going through the callstack (using up and down command in gdb) leading to this function call can inspect if the node has parent or scope pointers set. If not, you can add such operations to fix bugs related NULL pointers.

#### Set a condition to Breakpoints

In real codes, there are hundreds of objects of same class type (e.g. SgForStatement). Many of them come from header files and will be present in AST. We should only stop when it mathes the one we want to inspect. Often, we can use the memory address of the object as a condition.

#### Use Watchpoints

You can use a watchpoint to stop execution whenever the value of an expression changes, without having to predict a particular place where this may happen. (This is sometimes called a data breakpoint.)
Watchpoints can be treated as special types of breakpoints. They will stop when the watched memory locations have value changes. This is especially useful when you want to know when some variable (or field of an object) is set to some value or cleared its value. For example, often a bug is related to some NULL value of some fields of a node. The fields may be set during construction of the node. But later mysteriously one field becomes NULL. It is extremely hard to find when this happens without using watchpoint.
For example, we want to watch the value changes to the parent field of the SgForStatement matching the memory address of the 2nd loop.
* We first stop at a breakpoint where we have access to the node's internal fields. This usually is done by stopping at SgForStatement::post_construction_initialization.
* Once the internal variables are visible in gdb at the proper breakpoint, we can grab the memory address of the internal variable. This requires your knowledge of how internal variables are named. You can either look at the class declaration of the object, or guess it by convention. For example, mostly something with an access function like get_something has a corresponding internal variable named p_something in ROSE AST node types.
* Finally, we have to watch the deferenced value of the memory address (watch *address). Watching the memory address (watch address) is to watch a constant value. It won't work.

## A translator shipped with ROSE

This is also called in-tree or in-sourcetree build. libtool is used to build the translators.
ROSE turns on -O2 and -g by default so the translators shipped with ROSE should already have some debugging information available. But some variables may be optimized away. To preserve the max debugging information, you may have to reconfigure/recompile rose to turn off optimizations.
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:
* Find the real executable in the .lib directory then debug the real executables there
* Use libtool command line as follows:
If you can set up alias command in your .bashrc, add the following:
then all your debugging sessions can be as simple as
The remaining steps are the same as a regular gdb session with the typical operations, such as breakpoints, printing data, etc.

### Example 2: Fixing a real bug in ROSE

1. Reproduce the reported bug:
Ah, so we've failed an assertion within the virtualCFG.h header file on line 111:
And the error was produced by running the lt-testVirtualCFG libtool executable translator, i.e. the actual translator name is testVirtualCFG (without the lt- prefix).
2. Run the same translator command line with Libtool to start a GDB debugging session:
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:
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:
5. Next, we'll move backwards (or upwards) in the program to get to the point of assertion:
Okay, so the assertion is inside of a constructor for CFGEdge:
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:
So src.getNode is returning a non-null pointer to an SgNode. How bout tgt.getNode?
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:
Okay, it's failing so we know that the assignment to enclosingFunc is NULL.
Okay, we're inside of an SgReturnStmt object. Let's set a break point where enclosingFunc is being assigned to:
So this is the line we're examining:
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.
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.
We added the necessary logic to make the function complete, tested it to verify its correctness, and then resolved the bug.

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

### Method 1: New simple ways to add

Robb Matzke added a new feature in ROSE so you can more easily add a new project into ROSE/projects
* Create a $ROSE/projects/whatever directory.
* In that directory, create a "rose.config" file
* In that file, add the line AC_CONFIG_FILES(projects/whatever/Makefile)
rose/config/support-projects.m4 will be updated by running ./build.
You still need to have your Makefile.am. One simplest example is
* https://github.com/rose-compiler/rose-develop/blob/master/projects/SnippetTools/rose.config
* https://github.com/rose-compiler/rose-develop/blob/master/projects/SnippetTools/Makefile.am

### Method 2: 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", "config/support-rose.m4", "Makefile.am", and any necessary source files, scripts, tests, etc.
* The "README" should provide an explanation about the project purpose, algorithm, design, implementation, etc.
* The "support-rose.m4" 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.
* The "Makefile.am" serves as the input to the GNU automake system that ROSE employs to generate Makefiles.
* Each project should also include all necessary source files, documentation, and test cases.

#### Setting up support-rose.m4

The "config/support-rose.m4" 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:
Since all configuration for the project is encapsulated in the "support-rose.m4" 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 "support-rose.m4", or it can be removed by removing its directory. The "build" and "configure" scripts should be rerun after any of these changes.
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).

### 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:
* 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 be near the top of the Makefile.am.
* 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.
* INCLUDES: This would have 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.
* 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.
* 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.
* check-local: This is the target that will be called from the higher level Makefiles when make check is called.
* 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).

### 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 directory into ROSE: https://github.com/rose-compiler/rose/commit/edf68927596960d96bb773efa25af5e090168f4a
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
* a README file explaining what this project is about, algorithm, design, implementation, etc
* a translator acts as a driver of your project
* additional source files and headers as needed to contain the meat of your project
* test input files
* Makefile.am to
** compile and build your translator
** 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
* Add one more subdir entry into projects/Makefile.am for your project directory
* Add one line into config/support-rose.m4 for EACH new Makefile (generated from each Makefile.am) used by your projects.

### 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 Versioning.
From projects/RosePoly:

### Generate Doxygen Documentation

0. Install Doxygen tool
Using MacPorts for Apple's Mac OS:
Using one of the LLNL machines:
1. Create a Doxygen configuration file
2. Customize the configuration file (Doxyfile):
3. Generate the Doxygen documentation
4. View and verify the HTML documentation
5. Add target to your Makefile.am to generate the documentation

## 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 the work

### 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
* find a proper input file
* 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.
* 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:
* You can reproduce the bug reliably. Bingo! Go to the next step.
* You cannot reproduce the bug. Either the bug report is invalid or you have to keep trying.
* You can reproduce the bug once a while (random errors). Oops. This is kind of difficult situation.

### 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.
** 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.
* forward 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.

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

## How to add a ROSE commandline option

Often a feature added into ROSE comes with a set of command line options. These options can enable and customize the feature.
For example, the OpenMP support in ROSE is disabled by default. A special option is need to enable it. Also, the support can be as little as simply parsing the OpenMP directive or as complex as translating into multithreaded code.
This HOWTO quickly go through key steps to add options.

### internal flags

Options need to be stored somewhere. There are several choices for the storage,
* as a data member of SgProject , if the optiona is applicable to all files associated with a SgProject
* as a data member of SgFile, if the option is applicable to a single source file, or
* a member variable in a namespace you define, if the option is for some transformation or analysis.
If the option can be as specific as per file, it is recommended to add a new data member to SgFile to save the option value.
For example, here is a command line option to turn on the UPC language support:
ROSE/src/ROSETTA/src/support.C // add a date member for SgFile
ROSETTA process this information to automatically generate a member and the corresponding member access functions (set/get_member).

### process the option

Command line options should be handled within src/frontend/SageIII/sage_support/cmdline.cpp .
File level options are handled by void SgFile::processRoseCommandLineOptions ( vector<string> & argv )
Example code for processing the -rose:openmp option
ROSE commandline options should be removed after being processed, to avoid confusing the backend compiler
SgFile::stripRoseCommandLineOptions ( vector<string>& argv ) should have the code to strip off the option.

### use the option

In your code, you can use the automatically generated access functions to set/retrieve the stored option values.
For example

### document the option

Any option should be explained by the online help output.
Please add brief help text for your option in void SgFile::usage ( int status ) of ./src/frontend/SageIII/sage_support/cmdline.cpp: