org.eclipse.photran-dev-docs/dev-guide/cdt.ltx-inc

\section{Introduction}

The C/C++ Development Tools (CDT)\footnote{See
\url{http://www.eclipse.org/cdt/}} enables Eclipse to function as a first-class
C/C++ IDE. CDT provides features that a programmer expects from an IDE such
as project management, automated build, integrated debugging, etc. In addition,
CDT also provides extension points for writing IDEs for other programming
languages that follow the C/C++ edit-compile-debug-compile cycle closely;
Fortran is one such language.

Photran builds upon the CDT by leveraging its extension points. As such, it
needs to follow certain conventions and expectations of the CDT. In this
chapter, we discuss those conventions and expectations.

\section{CDT Terminology}

The following are CDT terms that will be used extensively when discussing
Photran.

\begin{itemize}

\item \textbf{Standard Make projects} are ordinary Eclipse projects, except that
CDT and Photran recognize them as being ``their own'' type of project (as
opposed to, say, projects for JDT, EMF, or another Eclipse-based tool). Users
must supply their own Makefile, typically with targets ``clean'' and ``all.''
CDT/Photran cleans and builds the project by running \texttt{make}.

\item \textbf{Managed Make projects} are similar to standard make projects,
except that CDT/Photran automatically generates a Makefile and edits the
Makefile automatically when source files are added to or removed from the
project. The \textbf{Managed Build System} is the part of CDT and Photran that
handles all of this.

\item \textbf{Binary parsers} are able to detect whether a file is a legal
executable for a platform (and extract other information from it). CDT
provides binary parsers for Windows (PE), Linux (ELF), Mac OS X (Mach), and
others. Photran does not provide any additional binary parsers.

\item \textbf{Error parsers} are provided for many compilers. CDT provides a gcc
error parser, for example. Photran provides error parsers for Lahey Fortran, F,
g95, and others. Essentially, error parsers scan the output of \texttt{make} for
error messages for their associated compiler. When they see an error message
that they recognize, they extract the filename, line number, and error message,
and use it to populate the Problems View. See
Appendix~\ref{ap:creating_an_error_parser} for an example on how to create an
error parser.

\item CDT keeps a \textbf{model} of all of the files in a project. The model is
essentially a tree of \textbf{elements}, which all derive from the (CDT Core)
class \texttt{ICElement}. It is described in the next section.

\end{itemize}

\section{The Model}

\emph{This section describes the CDT model in detail. Understanding the CDT
model is useful for contributors who are interested in modifying the UI and how
Fortran projects are managed in the Fortran perspective. Contributors who are
interested in creating refactorings and program analysis tools should
familiarize themselves with the Abstract Syntax Tree (AST) and Virtual Program
Graph (VPG) described in Chapter~\ref{cha:parsing}.}

The Fortran Projects view in Photran is essentially a visualization of
the CDT's \textit{model}, a tree data structure describing the contents
of all Fortran Projects in the workspace as well as the high-level contents
(functions, aggregate types, etc.) of source files.

Alain Magloire (CDT) describes the model, A.K.A. the \texttt{ICElement}
hierarchy, in the thread ``Patch to create ICoreModel interface'' on the cdt-dev
mailing list:

{\footnotesize
\begin{quote}
\begin{verbatim}
So I'll explain a little about the ICElement and what we get out of it for
C/C++.

The ICElement hierarchy can be separated in two:
(1) - how the Model views the world/resources (all classes above ITranslationUnit)
(2) - how the Model views the world/language (all classes below ITranslationUnit).

How we(C/C++) view the resources:
- ICModel  --> [root of the model]
  - ICProject --> [IProject with special attributes/natures]
    - ISourceRoot --> [Folder with a special attribute]
      - ITranslationUnit --> [IFile with special attributes, e.g. extensions *.c]
      - IBinary --> [IFile with special attributes, elf signature, coff etc]
      - IArchive --> [IFile with special attributes, "<ar>" signature]
      - ICContainer -> [folder]

There are also some special helper classes
  - ILibraryReference [external files use in linking ex:libsocket.so, libm.a, ...]
  - IIncludeReference [external paths use in preprocessing i.e. /usr/include, ...]
  - IBinaryContainer [virtual containers regrouping all the binaries found
    in the project]

This model of the resources gives advantages:
- navigation of the binaries,
- navigation of the include files not part of the workspace (stdio.h, socket.h, etc)
- adding breakpoints
- search
- contribution on the objects
etc.....

[...]

(2) How we view the language.

Lets be clear this is only a simple/partial/incomplete view of the language. For
example, we do not drill down in blocks, there are no statements(if/else
conditions) etc .... For a complete interface/view of the language, clients
should use the __AST__ interface.
\end{verbatim}
\end{quote}
}

\pagebreak

From another of Alain's posts in that thread:

{\footnotesize
\begin{quote}
\begin{verbatim}
Lets make sure we are on the same length about the ICElement hierarchy.
It was created for a few reasons:

- To provide a simpler layer to the AST.  The AST interface is too complex
  to handle in most UI tasks.
- To provide objects for UI contributions/actions.
- The glue for the Working copies in the Editor(CEditor), IWorkingCopy class
- The interface for changed events.
- ...

Basically it was created for the UI needs: Outliner, Object action contributions,
C/C++ Project view and more.

The CoreModel uses information taken from:
- the Binary Parser(Elf, Coff, ..)
- the source Parser(AST parser)
- the IPathEntry classes
- the workspace resource tree
- The ResolverModel (*.c, *.cc extensions), ...

to build the hierarchy.
\end{verbatim}
\end{quote}
}

\shabox{The CDT model should \textbf{not} be confused with the Abstract Syntax
Tree (AST) model that is discussed in Section~\ref{sec:ast_structure}. They are
\textbf{not} identical. It is best to think of the CDT model as containing a
\emph{partial/simplified view} of the AST model to represent the
\emph{interesting} elements in the source code (program names, function names,
subroutine names) \textbf{in addition} to a model of the current workspace
resources (Fortran projects, Fortran source files, binary executables). \emph{In
other words, the CDT model knows about the language and the resources}. The AST,
on the other hand, completely models \emph{everything} in the source file (but
nothing about the resources), including low-level elements that the user is
unlikely to be interested in knowing about (assignment nodes, variable
declarations). While low-level, these elements are useful for refactoring and 
program analysis.}

By conforming to the CDT model, Photran is able to reuse various UI
elements for \emph{free}. For instance, the Outline View for Photran is managed
by CDT; Photran just needs to provide a CDT-compatible model to represent its
project and source files.

The \texttt{FortranLanguage} class is responsible for initializing concrete
classes that will build up the model that CDT expects. For more
information, refer to the FortranLanguage.java file in the
\texttt{org.eclipse.photran.cdtinterface} plug-in project.

There are \textbf{two} options for creating suitable \emph{model builders}:
\begin{enumerate}
\item The \texttt{org.eclipse.photran.cdtinterface} plug-in project defines the
\\ \texttt{org.eclipse.photran.cdtinterface.modelbuilder} extension point that
other plug-ins can extend. Plug-ins extending that extension point are
responsible for providing a suitable model builder. Using this option, it is
possible to have multiple model builders. The model builder to use can be
selected in the workspace preferences (under Fortran $>$ CDT Interface).

\item If there are no plug-ins that extend the
\texttt{org.eclipse.photran.cdtinterface.modelbuilder} extension point, then
Photran falls back on a default implementation. The default implementation is
provided by the \texttt{SimpleFortranModelBuilder} class. It relies on simple
lexical analysis to build the model. This simple model builder might not be able
to accurately handle the more complicated features of the Fortran language.
\end{enumerate}

The Photran VPG (see Section~\ref{sec:virtual_program_graph}) inside the
\texttt{org.eclipse.photran.core.vpg} project uses the first option to
contribute a model builder. The relevant classes are under the
\texttt{org.eclipse.photran.internal.core.model} package i.e.
\texttt{FortranModelBuilder}, \texttt{FortranModelBuildingVisitor} and 
\texttt{FortranParseTreeModelBuildingVisitor}.

As mentioned in the post by Alain, all model elements must implement the
\texttt{ICElement} interface for CDT to recognize them. In Photran, the
\texttt{FortranElement} class implements the \texttt{ICElement} interface and
serves as the base class for all Fortran elements such as subroutines,
functions, modules, variables, etc. Each subclass of \texttt{FortranElement}
corresponds to an element that can be displayed in the Outline View.

\section{Reusing UI Elements}

Various UI elements in Photran are also reused from the CDT through subclassing.
For instance, the \texttt{NewProjectDropDownAction} class shown in
Listing~\ref{lst:newprojectdropdownaction} is a subclass of
\texttt{AbstractWizardDropDownAction} declared in CDT.
\texttt{AbstractWizardDropDownAction} provides most of the implementation and
our subclass just provides the Photran-specific details such as the actual
action that will be invoked.
 
\begin{code}
\begin{lstlisting}
public class NewProjectDropDownAction extends AbstractWizardDropDownAction
{
	public NewProjectDropDownAction()
	{
		super();
		PlatformUI.getWorkbench().getHelpSystem().setHelp(this,
			 ICHelpContextIds.OPEN_PROJECT_WIZARD_ACTION);
	}
	
	protected IAction[] getWizardActions()
	{
		return FortranWizardRegistry.getProjectWizardActions();
	}
}
\end{lstlisting}
\caption{\texttt{NewProjectDropDownAction} class}
\label{lst:newprojectdropdownaction}
\end{code}

Our \texttt{NewProjectDropDownAction} is invoked through the right-click menu by
going to New... $>$ Other $>$ Fortran. It creates a new Fortran project in the
current workspace.

In addition, we could also customize the icons for each UI element by modifying
the appropriate attributes in the plugin.xml file in the
\texttt{org.eclipse.photran.cdtinterface} project.

\section{The CDT Debugger and \texttt{gdb}}

Currently, Photran re-uses the CDT debugger as-is and does not contribute any
enhancements to it. Here is a brief summary of how the debugger works:

\begin{itemize}

\item The so-called CDT debugger is actually just a graphical interface to
\texttt{gdb}, or more specifically to \texttt{gdb/mi}. So, if something doesn't
appear to work, it is advisable to try it in \texttt{gdb} directly or to use
another \texttt{gdb}-based tool such as DDD.

\item The debugger UI ``contributes'' breakpoint markers and actions to the
editor. The ``set breakpoint'' action, and the breakpoint markers that appear in
the ruler of the CDT (and Photran) editors are handled \textbf{entirely} by the
CDT debug UI; there is no code for this in Photran. The ``set breakpoint''
action is enabled by calling \lstinline!setRulerContextMenuId("#CEditorRulerContext");! 
in the \texttt{AbstractFortranEditor} constructor.

\item \texttt{gdb} reads debug symbols from the executable it is debugging.
That is how it knows what line it's on, what file to open, etc.  Photran
has \textit{nothing} to do with this: These symbols are written entirely
by the compiler.  Moreover, the compiler determines what shows up in the
Variables View.  If the debugger views seem to be a mess, it is the
compiler's fault, not Photran's.

\end{itemize}