% Plug-in Decomposition
\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.

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.

\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, and a
      simple lexical analyzer-based model builder (which, generally speaking,
      is not used)
\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}

For more information about CDT, see Chapter~\ref{cha:cdt}.

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

This is the Photran Core plug-in. It contains much of the Fortran-specific
``behind the scenes'' functionality:

\begin{itemize}
\item Utility classes
\item Error parsers for Fortran compilers
\item Fortran 95 lexical analyzer
\item Workspace preferences
\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 the GNU toolchain. Managed by Craig Rasmussen at LANL.

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

This contains the Fortran-specific components of the user interface:

\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 Chapter~\ref{cha:parsing}.

\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 Virtual Program Graph library (vpg-eclipse.jar)
\item Photran's Virtual Program Graph (VPG)
\item Utility classes (e.g., \texttt{SemanticError}, \texttt{LineCol})
\item Project property pages
\item 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. Managed 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-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.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}