| \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: |
| |
| \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} |
| |
| \pagebreak |
| |
| From another of Alain's posts in that thread: |
| |
| \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} |
| |
| \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} |