% Plug-in Decomposition
\vspace{-0.5in}

{\scriptsize Revision: \footnotesize \$Id: cha-plugins.ltx-inc,v 1.1 2010/05/21 20:12:20 joverbey Exp $ $ - based on 2008/08/08 nchen}

\section{Introduction}

This chapter presents a high-level overview of the different projects and
plug-ins in Photran. It serves as a guide for developers reverse-engineering
Photran to \emph{guess-and-locate} where certain components are. It also serves
as a guide for contributers on \emph{where} to put their contributions.

\section{The Rephraser Engine}

There are two major components in Photran's CVS repository: Photran itself, and another project called the Rephraser Engine.  For the most part, you will probably be able to ignore the Rephraser Engine, but it is helpful to know what it is.
(The Rephraser Engine will contribute a Rephraser Engine Plug-in Developer Guide to the runtime
workbench; this provides more information about these plug-ins.  Its sources are in the
org.eclipse.rephraserengine.doc.isv project.)

While developing Photran, one of our research objectives has been to create a common infrastructure that can be reused in refactoring tools for different languages. The Rephraser Engine is one part of this infrastructure: It contains base classes for refactorings, the virtual program graph (VPG), etc.  \textit{None of the classes in the Rephraser Engine know about Fortran, Photran, or CDT.}  They are completely language-independent.  However, many of the classes in Photran's refactoring engine inherit from base classes in the Rephraser Engine: They are ``specialized'' to work with Fortran.

In addition to Photran, Ralph Johnson's research group at UIUC is developing prototype refactoring tools for PHP, Lua, and BC; all of these use the Rephraser Engine.  Therefore, if you ever need to change a class in the Rephraser Engine, you should be sure that the change applies to all of these tools, not just Photran.

\section{Photran's Architecture: Overview and Dependencies}

Figure~\ref{fig:images_architecture_overview} illustrates the plug-in
decomposition of Photran and the Rephraser Engine, as well as their relationship
with CDT and the Eclipse Platform.  \textit{Pay careful attention to the
dependencies in this diagram.}  If you are implementing a feature but need to
introduce a dependency that is not present, you are probably implementing the
feature in the wrong component.  It may be necessary to add an extension point
to add your feature in the ``correct'' way.  This should be discussed on the
ptp-dev mailing list.

The following sections are grouped by feature. A feature is a collection of
related Eclipse plug-ins that the user can install as a whole.

%\begin{image}
\begin{sidewaysfigure}
	\centering
	\includegraphics[width=\textwidth]{images/photran_architecture.png}
	\caption{Plug-in decomposition of Photran and the Rephraser Engine}
	\label{fig:images_architecture_overview}
\end{sidewaysfigure}
%\end{image}

\section{Base Photran Feature: org.eclipse.photran-feature}

The following projects comprise the ``base'' of Photran.

\begin{itemize}

\item \textbf{org.eclipse.photran.cdtinterface}

This contains most of the components (core and user interface) related
to integration with the CDT.  It includes:
\begin{itemize}
\item The FortranLanguage class, which adds Fortran to the list of languages
      recognized by CDT
\item Fortran model elements and icons for the Outline and Fortran Projects views
\item An extension point for contributing Fortran model builders
\item The Fortran perspective, Fortran Projects view, and other CDT-based
      parts of the user interface
\item New Project wizards and Fortran project templates
\end{itemize}

More information about CDT integration is provided in Part~II of the
\textit{Photran Developer's Guide.}

\item \textbf{org.eclipse.photran.core}

This is the Photran Core plug-in. It contains much of the ``behind the scenes''
functionality which allows Eclipse to support Fortran projects (although it does
\textit{not} contain the Fortran parser/analysis infrastructure).

\begin{itemize}
\item Workspace preferences for Fortran projects
\item Error parsers for Fortran compilers
\item Utility classes
\end{itemize}

\item \textbf{org.eclipse.photran.managedbuilder.core}, \\
      \textbf{org.eclipse.photran.managedbuilder.gnu.ui}, \\
      \textbf{org.eclipse.photran.managedbuilder.ui}

Support for Managed Build projects using GNU Fortran (gfortran).  Originally created by
Craig Rasmussen at Los Alamos National Lab.

\item \textbf{org.eclipse.photran.ui}

This contains the Fortran-specific components of the user interface that are
not derived from CDT and do not depend on the Fortran parser.  These are:

\begin{itemize}
\item Fortran Editors
\item Preference pages
\end{itemize}

\end{itemize}

\section{Virtual Program Graph (VPG) feature: org.eclipse.photran.vpg-feature}

The following projects support parsing, analysis, and refactoring of Fortran
sources. They are written in Java 5. The Virtual Program Graph is described in
more detail in Part~II of the \textit{Photran Developer's Guide.}

\begin{itemize}

\item \textbf{org.eclipse.photran.core.vpg}

This contains the parsing, analysis, and refactoring infrastructure.
\begin{itemize}
\item Fortran parser and abstract syntax tree (AST)
\item Fortran preprocessor (to handle INCLUDE lines)
\item Parser-based model builder
\item Photran's Virtual Program Graph (VPG)
\item Utility classes (e.g., \texttt{SemanticError}, \texttt{LineCol})
\item Project property pages
\item Name binding analysis (equivalent to symbol tables)
\item Refactoring/program transformation engine
\item Refactorings
\end{itemize}

\item \textbf{org.eclipse.photran.core.vpg.tests}, \\
      \textbf{org.eclipse.photran.core.vpg.tests.failing}

JUnit Plug-in tests for the VPG core plug-in.

All tests in org.eclipse.photran.core.vpg.tests should pass. Test suites and
test cases are placed in the ``failing'' plug-in project until all of their
tests pass.

These plug-ins \textit{must} be run as a ``JUnit Plug-in Test'' (\textbf{not} a
``JUnit Test''). In the launch configuration, the environment variable TESTING
must be set to some non-empty value. (This ensures that the VPG will not try to
run in the background and interfere with testing.)

\item \textbf{org.eclipse.photran.ui.vpg}

UI contributions that depend on the \texttt{org.eclipse.photran.core.vpg}
plug-in. Currently, this includes the Open Declaration action, a project
property page where the user can customize the search path for Fortran modules
and include files, Fortran Search support, and all of the actions in the
Refactor menu.

\item \textbf{org.eclipse.photran.cdtinterface.vpg}

This contributes the Fortran model builder which constructs the model seen in
the Outline view and Fortran Projects view.  It uses the Fortran parser
contained in the org.eclipse.photran.core.vpg plug-in.

\end{itemize}

\section{XL Fortran Compiler Feature: org.eclipse.photran.xlf-feature}

The following are plug-ins to support the
\href{http://www-306.ibm.com/software/awdtools/fortran/}{XL Fortran compiler}.

\begin{itemize}
\item \textbf{org.eclipse.photran.core.errorparsers.xlf}, \\
      \textbf{org.eclipse.photran.managedbuilder.xlf.ui}

Support for Managed Build projects using XL toolchains. Originally created by Craig
Rasmussen at LANL.

\end{itemize}

\section{Intel Fortran Compiler Feature: org.eclipse.photran.intel-feature}

The following are plug-ins to support the \href{http://www.intel.com/cd/software/products/asmo-na/eng/compilers/284132.htm}{Intel Fortran Compiler}.

\begin{itemize}
\item \textbf{org.eclipse.photran.core.intel}, \\
      \textbf{org.eclipse.photran.managedbuilder.intel.ui}

Support for Managed Build projects using Intel toolchains. Maintained by Bill
Hilliard at Intel.

\end{itemize}

%\section{Rephraser Engine}
%
%The following plug-ins comprise the Rephraser Engine, a language-independent indexing and
%refactoring infrastructure that serves as the basis for Photran's refactoring engine.
%The Rephraser Engine will contribute a Rephraser Engine Plug-in Developer Guide to the runtime
%workbench (sourced in org.eclipse.rephraserengine.doc.isv); this provides more information about
%these plug-ins.  Starred plug-ins are not distributed to end users.
%
%\begin{itemize}
%\item \textbf{org.eclipse.rephraserengine-feature}
%\item \textbf{org.eclipse.rephraserengine-support}*
%\item \textbf{org.eclipse.rephraserengine.core}
%\item \textbf{org.eclipse.rephraserengine.core.refactoring}
%\item \textbf{org.eclipse.rephraserengine.core.vpg}
%\item \textbf{org.eclipse.rephraserengine.core.vpg.tests}*
%\item \textbf{org.eclipse.rephraserengine.doc.isv}*
%\item \textbf{org.eclipse.rephraserengine.examples.text}*
%\item \textbf{org.eclipse.rephraserengine.examples.testing}*
%\item \textbf{org.eclipse.rephraserengine.testing.junit3}*
%\item \textbf{org.eclipse.rephraserengine.ui}
%\item \textbf{org.eclipse.rephraserengine.ui.refactoring}
%\item \textbf{org.eclipse.rephraserengine.ui.vpg}
%\end{itemize}

\section{Non-plug-in projects}

The following projects are in CVS but are not distributed to users:

\begin{itemize}

\item \textbf{org.eclipse.photran-dev-docs}

Developer documentation, including this document (\texttt{dev-guide/*}), CVS
instructions (\texttt{dev-guide/cvs-instructions.pdf}), the materials from our
presentation at EclipseCon 2006 on adding a new language to the CDT, and a
spreadsheet mapping features in the Fortran language to JUnit tests
(\texttt{language-coverage/*}).

\item \textbf{org.eclipse.photran-samples}

A Photran project containing an assortment of Fortran code.

\end{itemize}