User:Charlesareynolds/sandbox

Writing a ROSE Tool

Introduction

Purpose

This book helps you write a ROSE Tool. A ROSE Tool is a software analysis and/or transformation tool built using ROSE.

ROSE

ROSE is short for the ROSE Compiler Infrastructure, developed at Lawrence Livermore National Laboratory (LLNL). ROSE is an open source framework for building source-to-source program transformation and analysis tools for large-scale software written in C, C++, FORTRAN, Java, Python and other languages. ROSE is written primarily in C++ and includes a run-time library, example tools built using the library, and extensive test code.

The ROSE library provides:

• The ability to parse code into an Abstract Syntax Tree (AST) containing all the input code's syntax and static semantics
• Extensive facilities to query and modify the AST
• The ability to "unparse" an AST back into valid source code again
• Various support facilities, such as command line parsing and logging

ROSE Tools

A ROSE Tool is a program built using the ROSE library. Usually, you run it separately on each source file making up the subject code. It looks like a compiler to a build system. To use a ROSE Tool, tell the build system normally used to build the subject code to call the tool instead of the normal compiler, passing it the same source files and switches the regular compiler expects.

A ROSE tool may be a transformation or an analysis tool.

• A ROSE transformation tool compiles the original source code into an AST, alters the AST, generates altered source code, and calls the normal compiler on the altered code.
• An ROSE analysis tool compiles the original source code into an AST, performs some analysis on the AST, outputs the results, and does not generate code. It may call the normal compiler on the original source file, so that the build system behaves normally.

ROSE Users

ROSE is an open-source project, with many users and developers. Each falls into one or more categories:

• Tool User: Uses a ROSE Tool to analyze or modify code.
• Tool Writer: Writes or maintains a ROSE Tool.
• Core Developer: Maintains or adds to the core ROSE functionality found in the ROSE library and maintains the associated tests. Fixes bugs, ports ROSE to new platforms adds new languages. Most ROSE Core developers work at LLNL.

Documentation

Start with this Wikibook if you want to build a ROSE Tool. This book is part explanation and part tutorial.

Additional ROSE documentation can be found in several places:

• The official rosecompiler.org website
  • The documentation page
  • The Doxygen, or HTML_Reference pages
    • Modules, Namespaces, Classes, Files, Examples, "Where new users should start"
    • Tool development
• The ROSE Compiler Framework Wikibook
  • The how-tos
  • ROSE Tools
• The Developer's Guide (pdf, Atlassian)
• Tutorials on GitHub (2013)
• User Manual on GitHub (2013)

Getting Started

Approach

First, we will build and run an example ROSE Tool. Then, we will examine what goes into a ROSE Tool, and touch on what can be done with the subject code once it has been parsed into an AST.

Initially, this book will focus on writing a ROSE Tool on a Red Hat-based Linux/Intel high-performance computing (HPC) system at Livermore Computing (LC) (part of LLNL).

Prerequisites

To write a ROSE Tool, you will need several things:

• Development system
  • ROSE installation This book covers building a ROSE Tool using the library from a ROSE installation. The alternative is to build ROSE from source ( >1M SLOC) first, which is only necessary for ROSE Core work.
  • C++ editor, compiler, etc.
  • For LLNL LC development, you will need an account on a CZ or RZ system.
• "Subject" code to transform or analyze
  • Build system for subject code
  • Compiler for subject code (must match the one the ROSE installation is expecting)
• Requirements
  • Test code
• Knowledge of subject code's language and semantics

Building and Running a Tool on an LLNL LC System

ROSE Installation

On LLNL LC systems, ROSE is installed as described here(CZ login needed) and here(RZ login needed). The installation has bin, include, and lib directories.

• bin contains the rose_config build helper tool, and some existing ROSE Tool executables.
• include and lib contain the files needed to build new tools.
• Building the tool
  • Scripts, Makefiles, rose_config
• Running the tool
  • ROSE and BOOST libraries

Anatomy of a Tool

• Tool template
• Example tool
• Processing command line switches
• Logging
• Parsing
• Traversing parsed AST
• Processing an AST node

Gotchas

• Boost Library
• Compiler version
• Build System