\chapter{Identity Translator}

\paragraph{What To Learn From This Example}
This example shows a trivial ROSE translator which does not transformation,
but effectively wraps the the backend vendor compiler in an extra layer of 
indirection.
% but takes in source code, constructs the AST, generates source code from
% the AST, and then compiles the generated source code to build an executable or
% object file.  It acts just like the vendor compiler (which it uses
% internally as a backend compiler) and effectively wraps the vendor compiler
% in an extra layer of indirection.
\vspace{0.25in}

  Using the input code in Figure~\ref{Tutorial:exampleInputCode_IdentityTranslator}
we show a translator which builds the AST (calling {\tt frontend()}), generates 
the source code from the AST, and compiles the generated code using the backend vendor 
compiler\footnote{Note: that the backend vendor compiler is selected at configuration time.}.
Figure~\ref{Tutorial:exampleIdentityTranslator} shows the source code for this
translator.
% the construction of the AST is identical to the previous code, but
% we make an explicit call to the ROSE {\tt backend()} function.
The AST graph is generated by the call to the {\tt frontend()} using the
standard {\tt argc} and {\tt argv} parameters from the C/C++ {\tt main()} function.
In this example code, the variable {\tt project} represents the root of the AST\footnote{
The AST is technically a {\em tree} with additional attributes that are represented by 
edges and additional nodes, so the AST is a tree and the AST {\em with} attributes is
a more general graph containing edges that would make it technically {\em not} a tree.}.
The source code also shows what is an optional call to check the integrity of
the AST (calling function {\tt AstTests::runAllTests()}); this function has no 
side-effects on the AST.
The source code generation and compilation to generate the object file or executable are
done within the call to {\tt backend()}.

The identity translator (\textit{identityTranslator}) is probably the
simplest translator built using ROSE. It is built by default and can be found in \\
\textit{ROSE\_BUILD/exampleTranslators/documentedExamples/simpleTranslatorExamples} 
or \\
\textit{ROSE\_INSTALL/bin}.  It is often used to test if
ROSE can compile input applications.
Typing \textit{identityTranslator --help} will give you more information
about how to use the translator.

\begin{figure}[!h]
{\indent
{\mySmallFontSize


% Do this when processing latex to generate non-html (not using latex2html)
\begin{latexonly}
   \lstinputlisting{\TutorialExampleDirectory/identityTranslator.C}
\end{latexonly}

% Do this when processing latex to build html (using latex2html)
\begin{htmlonly}
   \verbatiminput{\TutorialExampleDirectory/identityTranslator.C}
\end{htmlonly}

% end of scope in font size
}
% End of scope in indentation
}
\caption{Source code for translator to read an input program 
         and generate an object code (with no translation).}
\label{Tutorial:exampleIdentityTranslator}
\end{figure}

\begin{figure}[!h]
{\indent
{\mySmallFontSize


% Do this when processing latex to generate non-html (not using latex2html)
\begin{latexonly}
   \lstinputlisting{\TutorialExampleDirectory/inputCode_IdentityTranslator.C}
\end{latexonly}

% Do this when processing latex to build html (using latex2html)
\begin{htmlonly}
   \verbatiminput{\TutorialExampleDirectory/inputCode_IdentityTranslator.C}
\end{htmlonly}

% end of scope in font size
}
% End of scope in indentation
}
\caption{Example source code used as input to identity translator.}
\label{Tutorial:exampleInputCode_IdentityTranslator}
\end{figure}

Figure~\ref{Tutorial:exampleOutputFromTranslator} shows the generated code from the
processing of the {\tt identityTranslator} build using ROSE and using the input file
shown in figure~\ref{Tutorial:exampleInputCode_IdentityTranslator}.
This example also shows that the output generated from and ROSE translator is
a close reproduction of the input; preserving all comments, preprocessor
control structure, and most formating.  Note that all macros are expanded in
the generated code.

\begin{figure}[!h]
{\indent
{\mySmallFontSize


% Do this when processing latex to generate non-html (not using latex2html)
\begin{latexonly}
   \lstinputlisting{\TutorialExampleBuildDirectory/rose_inputCode_IdentityTranslator.C}
\end{latexonly}

% Do this when processing latex to build html (using latex2html)
\begin{htmlonly}
   \verbatiminput{\TutorialExampleBuildDirectory/rose_inputCode_IdentityTranslator.C}
\end{htmlonly}

% end of scope in font size
}
% End of scope in indentation
}
\caption{Generated code, from ROSE identity translator, sent to the backend (vendor) compiler.}
\label{Tutorial:exampleOutputFromTranslator}
\end{figure}

  In this trivial case of a program in a single file, the translator
compiles the application to build an executable (since {\tt -c}
was not specified on the command-line).




