diff options
author | Jeffrey Overbey | 2008-07-30 17:45:29 +0000 |
---|---|---|
committer | Jeffrey Overbey | 2008-07-30 17:45:29 +0000 |
commit | fac36f8fb1f5240c73608ee8ed4af99cb432f2e8 (patch) | |
tree | 7f3418c63adea92d55c358f763ea57c6580000e5 | |
parent | 97b29f59c413a0f1f386d20bea5d272b98f1f7b7 (diff) | |
download | org.eclipse.photran-fac36f8fb1f5240c73608ee8ed4af99cb432f2e8.tar.gz org.eclipse.photran-fac36f8fb1f5240c73608ee8ed4af99cb432f2e8.tar.xz org.eclipse.photran-fac36f8fb1f5240c73608ee8ed4af99cb432f2e8.zip |
Restructured files (Nick Chen)
14 files changed, 134 insertions, 87 deletions
diff --git a/org.eclipse.photran-dev-docs/dev-guide/.cvsignore b/org.eclipse.photran-dev-docs/dev-guide/.cvsignore new file mode 100644 index 00000000..c4e2276b --- /dev/null +++ b/org.eclipse.photran-dev-docs/dev-guide/.cvsignore @@ -0,0 +1 @@ +*.fdb_latexmk diff --git a/org.eclipse.photran-dev-docs/dev-guide/a1-cvs.ltx-inc b/org.eclipse.photran-dev-docs/dev-guide/app-cvs.ltx-inc index ad4a2544..3f072551 100644 --- a/org.eclipse.photran-dev-docs/dev-guide/a1-cvs.ltx-inc +++ b/org.eclipse.photran-dev-docs/dev-guide/app-cvs.ltx-inc @@ -111,4 +111,4 @@ If you already have CDT 5.0 installed and do not need to edit the CDT source cod engine require closed-source code that is not available in CVS. A warning will appear in the JUnit runner if this code is not available.} -\end{enumerate}
\ No newline at end of file +\end{enumerate} diff --git a/org.eclipse.photran-dev-docs/dev-guide/a2-error-parsers.ltx-inc b/org.eclipse.photran-dev-docs/dev-guide/app-error-parsers.ltx-inc index 2f13cd89..2f13cd89 100644 --- a/org.eclipse.photran-dev-docs/dev-guide/a2-error-parsers.ltx-inc +++ b/org.eclipse.photran-dev-docs/dev-guide/app-error-parsers.ltx-inc diff --git a/org.eclipse.photran-dev-docs/dev-guide/a3-rename-tests.ltx-inc b/org.eclipse.photran-dev-docs/dev-guide/app-rename-tests.ltx-inc index bdddc244..e158f6e1 100644 --- a/org.eclipse.photran-dev-docs/dev-guide/a3-rename-tests.ltx-inc +++ b/org.eclipse.photran-dev-docs/dev-guide/app-rename-tests.ltx-inc @@ -90,4 +90,4 @@ should be renamable to which other identifiers: /* contained */ new boolean[] { false, false, false, false, false, ... /* external */ new boolean[] { false, false, false, false, false, ... ... -\end{verbatim}}
\ No newline at end of file +\end{verbatim}} diff --git a/org.eclipse.photran-dev-docs/dev-guide/authors.tex b/org.eclipse.photran-dev-docs/dev-guide/authors.ltx index 0bacd182..0bacd182 100644 --- a/org.eclipse.photran-dev-docs/dev-guide/authors.tex +++ b/org.eclipse.photran-dev-docs/dev-guide/authors.ltx diff --git a/org.eclipse.photran-dev-docs/dev-guide/build.xml b/org.eclipse.photran-dev-docs/dev-guide/build.xml index cbef9568..5683fd1d 100644 --- a/org.eclipse.photran-dev-docs/dev-guide/build.xml +++ b/org.eclipse.photran-dev-docs/dev-guide/build.xml @@ -28,7 +28,7 @@ failifexecutionfails="true"> <arg value="cvs-instructions.ltx" /> </exec> - <delete><fileset dir="." includes="*.aux *.log *.toc *.dvi *.ps" /></delete> + <delete><fileset dir="." includes="*.aux *.log *.toc *.dvi *.ps *.out" /></delete> <exec executable="bash"><arg value="-c" /><arg value="if [ "$$LOGNAME" == "joverbey" ]; then xpdf -paper letter dev-guide.pdf; fi" /></exec> </target> diff --git a/org.eclipse.photran-dev-docs/dev-guide/01-intro.ltx-inc b/org.eclipse.photran-dev-docs/dev-guide/cdt.ltx-inc index 1cd816b2..9384f48c 100644 --- a/org.eclipse.photran-dev-docs/dev-guide/01-intro.ltx-inc +++ b/org.eclipse.photran-dev-docs/dev-guide/cdt.ltx-inc @@ -1,27 +1,3 @@ -% Introduction - -\textit{Last Updated 4/4/07} - -Photran is a IDE for Fortran 90/95 and Fortran 77 that is built on top of -Eclipse. It is structured as an Eclipse feature, in other words, -as a set of plug-ins that are designed to be used together. -Starting with version 3.0, it is an extension of CDT, the Eclipse IDE for -C/C++. Previous versions of Photran were created by hacking a copy of the -CDT to support Fortran instead of C/C++, but now we have developed a -mechanism for adding new languages into the CDT, allowing the Fortran support -code to be in its own set of plug-ins. - -Our purpose in writing Photran was to create a refactoring tool for Fortran. -Thus, Photran has a complete parser and program representation. Photran -adds a Fortran editor and several preference pages to the CDT user interface, -as well as a Fortran Managed Make project type. - -This document explains the design of Photran so that you could fix a bug or -add a refactoring. You should know how to use Photran and how -the CDT works. You need to understand Eclipse and Eclipse plug-ins -before you read this document. We recommend \textit{The Java -Developer's Guide to Eclipse} for Eclipse newcomers. - \section{CDT Terminology} The following are CDT terms that will be used extensively when discussing @@ -30,40 +6,34 @@ Photran. \begin{itemize} \item \textbf{Standard Make projects} are ordinary Eclipse projects, except that -the 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). -The user must supply their own Makefile, typically with targets ``clean'' -and ``all.'' CDT/Photran cleans and builds the project by running -\texttt{make}. +the 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). The user +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. +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). -The 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 they can recognize, they extract the -filename, line number, and error message, and use it to populate the -Problems view. - -\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 a (CDT Core) class \texttt{ICElement}. It is described -in the next section. +executable for a platform (and extract other information from it). The CDT +provides binary parsers for Windows (PE), Linux (ELF), Mac OS X (Mach), and +others. Photran does not provide any additional binary parsers. -\end{itemize} +\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 +they can recognize, they extract the filename, line number, and error message, +and use it to populate the Problems view. +\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 a (CDT Core) +class \texttt{ICElement}. It is described in the next section. +\end{itemize} \section{The Model} @@ -78,8 +48,8 @@ hierarchy, in the thread 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++. +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) @@ -87,21 +57,22 @@ The ICElement hierarchy can be separated in two: 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, for example extensions *.c] - - IBinary --> [IFile with special attributes, elf signature, coff etc...] - - IArchive --> [IFile with special attributes, "<ar>" signature] - - ICContainer -> [folder] + - 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 find in the project] + - 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 ...) +- navigation of the include files not part of the workspace (stdio.h, socket.h, etc) - adding breakpoints - search - contribution on the objects @@ -111,9 +82,10 @@ 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. +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} From another one of Alain's posts in that thread: @@ -165,3 +137,16 @@ Variables view. If the debugger views seem to be a mess, it is the compiler's fault, not Photran's. \end{itemize} + +% TODO: Stuff to add-in from Jeff's e-mail + +% Contributed to CDT: +% FortranLanguage (contributed to org.eclipse.cdt.core.language) +% Contributes a model builder and possibly a DOM parser to CDT. Note that these are contributed to extension points defined in org.eclipse.photran.cdtinterface, which in turn contributes them to org.eclipse.cdt.core.language via the FortranLanguage class. +% Reused from CDT: +% Some UI reused through copying (no better alternative): FortranPerspectiveFactory, large parts of org.eclipse.photran.cdtinterface's plugin.xml +% Lots of UI reused through subclassing: FortranView, NewFileDropDownAction, and many others +% FortranElement (base class for elements in Photran's model) subclasses from CDT model classes +% Some portions of the editor reused from CDT. Would have to read the code to remember the details. +% I'm not sure about Managed Make. +% The debugger is reused as-is. The user is able to set breakpoints in the Fortran editor because we reuse the C Editor's ruler context (see AbstractFortranEditor ctor). diff --git a/org.eclipse.photran-dev-docs/dev-guide/cvs-instructions.ltx b/org.eclipse.photran-dev-docs/dev-guide/cvs-instructions.ltx index dd6da0c3..984cbf3b 100644 --- a/org.eclipse.photran-dev-docs/dev-guide/cvs-instructions.ltx +++ b/org.eclipse.photran-dev-docs/dev-guide/cvs-instructions.ltx @@ -19,6 +19,6 @@ \maketitle -\input{a1-cvs.ltx-inc} +\input{app-cvs.ltx-inc} \end{document} diff --git a/org.eclipse.photran-dev-docs/dev-guide/dev-guide.ltx b/org.eclipse.photran-dev-docs/dev-guide/dev-guide.ltx index ab5ed61c..b3b38c0b 100644 --- a/org.eclipse.photran-dev-docs/dev-guide/dev-guide.ltx +++ b/org.eclipse.photran-dev-docs/dev-guide/dev-guide.ltx @@ -4,9 +4,22 @@ %\usepackage{anysize} %\marginsize{0.5in}{0.5in}{0.5in}{0.5in} \usepackage{fullpage} - \usepackage{graphicx} +\usepackage{listings} +\lstset{numbers=left, numberstyle=\tiny, numbersep=5pt, captionpos=b, basicstyle=\footnotesize} + +\usepackage[pdftex]{hyperref} +\hypersetup{ + colorlinks,% + citecolor=black,% + filecolor=black,% + linkcolor=black,% + urlcolor=blue +} + + + \hyphenpenalty=5000 \tolerance=1000 @@ -18,7 +31,7 @@ \title{Photran 4.0 Developer's Guide} \author{ -\input{authors} +\input{authors.ltx} } \date{} @@ -29,29 +42,35 @@ %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Introduction} -\input{01-intro.ltx-inc} +\input{intro.ltx-inc} + +\chapter{Interactions with the CDT} +\input{cdt.ltx-inc} \chapter{Plug-in Decomposition} -\input{02-plugins.ltx-inc} +\input{plugins.ltx-inc} \chapter{Parsing and Program Analysis} -\input{03-parsing.ltx-inc} +\input{parsing.ltx-inc} \chapter{Refactoring} -\input{04-refactoring.ltx-inc} +\input{refactoring.ltx-inc} + +\chapter{Photran Editor} +\input{editor.ltx-inc} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \appendix \chapter{Getting the Photran 4.0 Sources from CVS} \vspace{0.5em} -\input{a1-cvs.ltx-inc} +\input{app-cvs.ltx-inc} \chapter{Creating an Error Parser} -\input{a2-error-parsers.ltx-inc} +\input{app-error-parsers.ltx-inc} \chapter{Creating Tests for the Rename Refactoring} -\input{a3-rename-tests.ltx-inc} +\input{app-rename-tests.ltx-inc} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \end{document} diff --git a/org.eclipse.photran-dev-docs/dev-guide/editor.ltx-inc b/org.eclipse.photran-dev-docs/dev-guide/editor.ltx-inc new file mode 100644 index 00000000..6a82ade8 --- /dev/null +++ b/org.eclipse.photran-dev-docs/dev-guide/editor.ltx-inc @@ -0,0 +1 @@ +Chapter to describe the Photran editor. We will focus on describing how the VPG editor actions work here. diff --git a/org.eclipse.photran-dev-docs/dev-guide/intro.ltx-inc b/org.eclipse.photran-dev-docs/dev-guide/intro.ltx-inc new file mode 100644 index 00000000..3c3b1af3 --- /dev/null +++ b/org.eclipse.photran-dev-docs/dev-guide/intro.ltx-inc @@ -0,0 +1,39 @@ +% Introduction + +\textit{Last Updated 08/01/07} + +Photran is an IDE for Fortran 90/95 and Fortran 77 that is built on top of +Eclipse. It is structured as an Eclipse feature, in other words, as a set of +plug-ins that are designed to be used together. Starting with version 3.0, it is +an extension of CDT, the Eclipse IDE for C/C++. Previous versions of Photran +were created by hacking a copy of the CDT to support Fortran instead of C/C++, +but now we have developed a mechanism for adding new languages into the CDT, +allowing the Fortran support code to be in its own set of plug-ins. + +Our purpose in writing Photran was to create a refactoring tool for Fortran. +Thus, Photran has a complete parser and program representation. Photran adds a +Fortran editor and several preference pages to the CDT user interface, as well +as a Fortran Managed Make project type. + +\section{How To Read This Guide} % (fold) +\label{sec:how_to_read_this_guide} + +This document explains the design of Photran so that interested contributors +could fix a bug or add a refactoring. Contributors should know how to use +Photran and how the CDT works. There is a short +\href{http://www.eclipse.org/photran/documentation.php}{\emph{Getting Started +Guide}} on the Photran website. + +Contributors also need to understand Eclipse and Eclipse plug-ins before you +read this document. We recommend reading +\href{http://www.amazon.com/Eclipse-Building-Commercial-Quality-Plug-Ins/dp/0321228472}{\emph{Building +Commercial-Quality Plug-ins}} and +\href{http://www.amazon.com/Java-Developers-Guide-Eclipse-2nd/dp/0321305027/}{\emph{The +Java Developer's Guide to Eclipse}} for Eclipse newcomers. + +This is a \emph{duplex} guide. The main chapters provide general descriptions of +the various components and how they interact. The appendix describe concrete +examples from Photran so that contributors can familiarize themselves with +actual code and implementation details. + +% section how_to_read_this_guide (end) diff --git a/org.eclipse.photran-dev-docs/dev-guide/03-parsing.ltx-inc b/org.eclipse.photran-dev-docs/dev-guide/parsing.ltx-inc index bb0edd4d..cad93b0d 100644 --- a/org.eclipse.photran-dev-docs/dev-guide/03-parsing.ltx-inc +++ b/org.eclipse.photran-dev-docs/dev-guide/parsing.ltx-inc @@ -46,7 +46,9 @@ until the AST is released (permanent) or garbage collected (transient). The \texttt{acquireTransient/PermanentAST} methods return an object implementing \texttt{IFortranAST}. -{\footnotesize\begin{verbatim} +\lstset{language=Java} + +\begin{lstlisting} public interface IFortranAST extends Iterable<Token> { /////////////////////////////////////////////////////////////////////////// @@ -69,7 +71,7 @@ public interface IFortranAST extends Iterable<Token> public Token findFirstTokenOnLine(int line); public Token findTokenByFileOffsetLength(IFile file, int offset, int length); } -\end{verbatim}} +\end{lstlisting} The \texttt{getRoot} method returns the root of the AST, while the \texttt{find...} methods provide an efficient means to search for tokens based on their lexical @@ -100,7 +102,7 @@ For example, \texttt{fortran95.bnf} defines a \textit{$<$ProgramUnit$>$} as foll An \texttt{ASTProgramUnitNode} object, then, provides the following interface. -{\footnotesize\begin{verbatim} +\begin{lstlisting} public class ASTProgramUnitNode extends ParseTreeNode { public ASTMainProgramNode getASTMainProgram() { ... } @@ -109,7 +111,7 @@ public class ASTProgramUnitNode extends ParseTreeNode public ASTModuleNode getASTModule() { ... } public ASTBlockDataSubprogramNode getASTBlockDataSubprogram() { ... } } -\end{verbatim}} +\end{lstlisting} \subsubsection{List Nodes (Recursive Productions)} @@ -169,12 +171,12 @@ The solution is to label the MainRange nonterminal with a caret (\^), indicating This means that accessor methods that would otherwise be in a separate MainRange object will be placed in the MainProgram object instead. This means that an \texttt{ASTMainProgramNode} object has the following interface. -{\footnotesize\begin{verbatim} +\begin{lstlisting}[numbers=none] public ASTProgramStmtNode getProgramStmt(); public ASTBodyNode getBody(); public ASTBodyPlusInternalsNode getBodyPlusInternals(); public ASTEndProgramStmtNode getEndProgramStmt(); -\end{verbatim}} +\end{lstlisting} \subsubsection{Tokens} @@ -257,4 +259,4 @@ The entire range of source text for that token's enclosing \texttt{ScopingNode} Open a file in the Fortran editor, and click Refactor $>$ (Debugging) $>$ Display Symbol Table for Current File. -Indentation shows scope nesting, and each line summarizes the information in a \texttt{Definition} object.
\ No newline at end of file +Indentation shows scope nesting, and each line summarizes the information in a \texttt{Definition} object. diff --git a/org.eclipse.photran-dev-docs/dev-guide/02-plugins.ltx-inc b/org.eclipse.photran-dev-docs/dev-guide/plugins.ltx-inc index 48022a52..48022a52 100644 --- a/org.eclipse.photran-dev-docs/dev-guide/02-plugins.ltx-inc +++ b/org.eclipse.photran-dev-docs/dev-guide/plugins.ltx-inc diff --git a/org.eclipse.photran-dev-docs/dev-guide/04-refactoring.ltx-inc b/org.eclipse.photran-dev-docs/dev-guide/refactoring.ltx-inc index 6084d0b7..3321c0e5 100644 --- a/org.eclipse.photran-dev-docs/dev-guide/04-refactoring.ltx-inc +++ b/org.eclipse.photran-dev-docs/dev-guide/refactoring.ltx-inc @@ -78,4 +78,4 @@ can be used as a starting point. The Rename refactoring (\texttt{org.eclipse.photran.internal.core.refactoring.RenameRefactoring}) and the Introduce Implicit None refactoring (\texttt{org.eclipse.photran.internal.core.refactoring.IntroImplicitNoneRefactoring}) -are non-trivial but readable and should serve as a model for building future Fortran refactorings.
\ No newline at end of file +are non-trivial but readable and should serve as a model for building future Fortran refactorings. |