org.eclipse.photran-dev-docs/dev-guide/cha-plugins.ltx-inc - ptp/org.eclipse.photran - Git at Google

 % 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}
	% 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}