| <?php require_once($_SERVER['DOCUMENT_ROOT'] . "/eclipse.org-common/system/app.class.php"); require_once($_SERVER['DOCUMENT_ROOT'] . "/eclipse.org-common/system/nav.class.php"); require_once($_SERVER['DOCUMENT_ROOT'] . "/eclipse.org-common/system/menu.class.php"); $App = new App(); $Nav = new Nav(); $Menu = new Menu(); include($App->getProjectCommon()); # All on the same line to unclutter the user's desktop' |
| |
| $pageTitle = "Suggestions for New Contributors"; |
| $pageKeywords = "photran, contributing"; |
| $pageAuthor = "Jeffrey Overbey"; |
| |
| # Paste your HTML content between the EOHTML markers! |
| $html = <<<EOHTML |
| |
| <div id="maincontent"> |
| <div id="midcolumn"> |
| <h1>$pageTitle</h1> |
| |
| <div class="homeitem3col"> |
| <h3>Getting Started</h3> |
| |
| <p>New Photran contributors are always welcome. Here are some suggestions for getting started.</p> |
| |
| <h4>All Developers</h4> |
| <ol> |
| <li> <b>Learn Java.</b> |
| Photran is built on top of Eclipse and is written in Java. Obviously, this means you need to know Java. |
| If you have programmed in C or C++, learning the basics of Java should only take a few weeks, and you will |
| find that programming in Java is far less painful than programming in C or C++. |
| <li> <b>Learn to Use Eclipse.</b> |
| Photran is essentially a Fortran add-on for Eclipse. If you have not used Eclipse before, or if you're not |
| quite sure what "perspectives" and "views" are, you should work through |
| a basic Eclipse tutorial before attempting to learn Photran. Start Eclipse, click on the Help menu, |
| and click Help Contents. Expand the Workbench User's Guide, expand Getting Started, and work through |
| the section labeled Basic Tutorial. |
| <li> <b>Learn to Use Photran.</b> |
| If you have not used Photran before, you should become a fluent Photran user before you try to add a new |
| feature or fix a bug in it. See the Documentation page on the Photran web site. Photran reuses many |
| components of the Eclipse C/C++ Development Tool (CDT), so you may want to focus on learning |
| CDT: Once you know how to use CDT, you will know how to use Photran. |
| <li> <b>Learn to use the JDT and PDE to Develop a Simple Plug-in.</b> |
| If you have never developed an Eclipse plug-in before, develop a simple plug-in, perhaps one which |
| adds an item to the menu bar which pops up a "Hello, world!" message box when you click it. |
| For example, work through Chapters 7 through 9 in <i>The Java Developer's Guide to Eclipse, 2/e</i> |
| by D'Anjou et al. This will also require you to learn how to do Java development in Eclipse, although |
| this should be easy if you already know how to do C/C++ and Fortran development in Eclipse. |
| <li> <b>Check Out Photran from CVS and Compile It.</b> |
| Read <a href="http://dev.eclipse.org/viewcvs/index.cgi/%7Echeckout%7E/org.eclipse.photran/org.eclipse.photran-dev-docs/dev-guide/cvs-instructions.pdf?cvsroot=Technology_Project">How |
| to Check Out Photran from CVS and Compile It</a>, and actually do it. Make sure you can compile |
| Photran. |
| <li> <b>Read the Photran Developer's Guide (Chapters 1 & 2).</b> |
| Read the first two chapters of the <a href="http://dev.eclipse.org/viewcvs/index.cgi/%7Echeckout%7E/org.eclipse.photran/org.eclipse.photran-dev-docs/dev-guide/dev-guide.pdf?cvsroot=Technology_Project">Photran |
| Developer's Guide</a>. These chapters apply to all developers. |
| <li> <b>Join the Mailing Lists.</b> |
| <ul> |
| <li> Join the main <a href="https://dev.eclipse.org/mailman/listinfo/photran">Photran |
| Mailing List</a>. This is where Photran users post questions and get answers. |
| If you have problems or questions about how to <i>use</i> Photran, this is a good place to start. |
| <li> Join the <a href="https://dev.eclipse.org/mailman/listinfo/photran-dev">Photran |
| Contributors' Mailing List</a>. This is where architectural/design issues are discussed, |
| new releases are planned, conference calls are announced, etc. |
| </ul> |
| <li> <b>Read about Our Coding Conventions.</b> |
| Read the <a href="http://dev.eclipse.org/conventions.html">Eclipse Naming, Coding, and JavaDoc Conventions</a>. |
| Look through some of the classes in org.eclipse.photran.internal.core.refactoring to get a feel for the coding |
| style adopted in Photran (but don't be surprised when you discover that not all of our 60,000 lines of |
| code adhere to our coding |
| standard). In general, we use 120-character lines, 4-column tabs, descriptive variable names, |
| and curly braces on the next line, etc. A copyright notice must appear at the top of every source file, |
| and every API class should be JavaDoc'ed. Vocabulary specific to that class appears in bold in the class |
| documentation, and method comments assume that the reader has already read the class documentation |
| (so that vocabulary can be used freely). |
| </ol> |
| |
| <h4>Developers of UI Enhancements</h4> |
| <ol> |
| <li> <b>Learn the Editor Framework, JFace Text.</b> |
| If you will be working on the Photran editor, read about the JFace Text framework (Chapter 26 in |
| D'Anjou et al.). It may not make sense immediately; that's OK. Use the sample XML editor as a starting |
| point. Try changing the syntax highlighting, or adding auto-indentation, or whatever feature(s) are |
| relevent to the work you want to do. Make sure you can implement them in a simple editor before tackling |
| the Photran editors. |
| <li> If you will be working on dialog boxes, you will need to learn the Standard Widget Toolkit. Depending on |
| what you will be working on--preference pages, project property dialogs, etc.--you may need to learn about |
| other parts of the Eclipse framework as well. Ask if you are not sure. |
| </ol> |
| |
| <h4>Developers of Program Analyses, Transformations, and Refactorings</h4> |
| <ol> |
| <li> <b>Learn Fortran.</b> |
| Work through <i>Fortran 95/2003 Explained</i> by Metcalf, Reid, and Cohen or another book on Fortran 90/95. |
| Depending on what you're writing, you might be able to ignore certain parts of the language. Ask if you |
| are not sure. |
| <li> <b>Read the Photran Developer's Guide (Remaining Chapters).</b> |
| Read the remaining chapters of the <a href="http://dev.eclipse.org/viewcvs/index.cgi/%7Echeckout%7E/org.eclipse.photran/org.eclipse.photran-dev-docs/dev-guide/dev-guide.pdf?cvsroot=Technology_Project">Photran |
| Developer's Guide</a>. Spend some time looking at the Fortran parsing grammar (fortran95.bnf) and familiarizing |
| yourself with the AST. |
| <li> <b>JUnit.</b> |
| If you will be working on refactorings or another non-UI part of Photran, you will probably need to write |
| unit tests. This is done in JUnit 3, which is nicely integrated with the Eclipse Java Development Tools |
| (JDT). See <a href="http://www.junit.org" target="_top">junit.org</a>. |
| </ol> |
| |
| </div> |
| |
| <script language="javascript"> |
| function toggle(id) |
| { |
| var e = document.getElementById(id); |
| if (e.style.display != 'none') |
| e.style.display = 'none'; |
| else |
| e.style.display = ''; |
| } |
| </script> |
| |
| <div class="homeitem3col"> |
| <h3>Projects for New Developers</h3> |
| |
| <p><b>Note on Project Difficulty.</b> I [Jeff] have implemented <i>pieces</i> of these projects at one time or |
| another, so these are informed estimates of difficulty based on technical experience. That said, I have obviously |
| not attempted to implement any of these projects in their entirety, |
| and there could be complications that I did not consider or that are not immediately apparent. |
| Conversely, seemingly difficult projects sometimes turn out to be surprisingly easy. |
| For CS427 students, your grade will be based on the actual difficulty of the project, not on how difficult |
| I estimated it to be, so if a project turns out to be easier or harder than anticipated, you should discuss |
| this with the course staff to establish a fair and reasonable set of objectives. |
| </p> |
| <p> |
| Note that "easy" means "easy relative to some other projects," not "any CS1 student |
| could do this project." Don't be insulted if it takes several frustrating hours to complete the project. |
| </p> |
| |
| <p align="center"><b>THESE PROJECT DESCRIPTIONS ARE UNDER REVISION.</b></p> |
| <script language="javascript"> |
| function expandAll() |
| { |
| toggle('semhi'); |
| toggle('ca'); |
| toggle('mp'); |
| toggle('ht'); |
| toggle('ai'); |
| toggle('fold'); |
| toggle('ref'); |
| toggle('search'); |
| toggle('pref'); |
| toggle('docv'); |
| toggle('complain'); |
| toggle('cancapid'); |
| toggle('cancapkw'); |
| toggle('alignid'); |
| toggle('elimspec'); |
| //toggle('com2mod'); |
| toggle('mod2mod'); |
| toggle('ralph'); |
| toggle('en'); |
| //toggle('gstub'); |
| //toggle('doxv'); |
| //toggle('gdox'); |
| toggle('test'); |
| } |
| </script> |
| <p align="center"> |
| <table align="center" border="0" cellspacing="0" cellpadding="0" style="border-width: 1px;"><tr><td> |
| <a href="javascript:expandAll();"><b>Click here to expand/collapse all descriptions</b></a> |
| </td></tr></table> |
| </p> |
| |
| <h2>UI Enhancements</h2> |
| <ul> |
| <li> <table border="0" cellspacing="0" cellpadding="0" width="75%"><tr><td nowrap align="left" width="85%"> |
| <a href="javascript:toggle('semhi');"> |
| Semantic highlighting |
| </a> |
| </td><td align="left"> |
| Moderate |
| </td></tr></table> |
| <div id="semhi" style="display: none; margin-left: 32px;"> |
| <p> |
| Photran currently supports syntactic highlighting: comments, keywords, identifiers, and string literals |
| are colored distinctly. Since this coloring is updated on every keystroke, it is done without using |
| the lexer or parser, instead using a fast but imperfect heuristic algorithm. |
| JDT and newer versions of CDT use <i>semantic highlighting,</i> which uses information from the parser |
| and a subsequent semantic analysis to do even more advanced highlighting. For example, in JDT, fields, |
| local variables, and static variables are colored differently, even though they're all identifiers |
| syntactically. Since it is unreasonable to do a full lexical analysis on every keystroke (we tried), |
| much less a full parse and semantic analysis, only syntactic highlighting is done as the user types. A |
| <i>reconciler</i> runs when the user stops typing (currently after 500 ms) and runs the parser and |
| semantic analysis in a separate thread; subsequently, the highlighting in the editor can be updated |
| in the UI thread. |
| <p> |
| This project essentially has two parts. One is identifying what types of semantic highlighting would be |
| done for Fortran (what are the different types of identifiers?); the other is modifying the Fortran |
| editor to support it. |
| <p> |
| You will need to implement this in the <i>experimental</i> editor located in the |
| org.eclipse.photran.ui.vpg plug-in (when you run Photran, right-click a file and choose |
| Open With > Fortran Editor (VPG Experimental Features); "EXPERIMENTAL" should be displayed |
| in 36-point letters at the top of the editor window). The JavaDoc and sample code in the |
| org.eclipse.photran.internal.ui.editor_vpg package should be particularly helpful. |
| <p> |
| Most of the CDT implementation is in org.eclipse.cdt.internal.ui.editor.Semantic*.java, but be aware |
| that our infrastructure is quite different from theirs, so it will be easier to implement this on your |
| own, working from the sample code. |
| <p> |
| <b>Bonus Points.</b> |
| Include a global preference page to allow user-customizable coloring and (more importantly) an option |
| to toggle semantic highlighting on and off. |
| </div> |
| <li> <table border="0" cellspacing="0" cellpadding="0" width="75%"><tr><td nowrap align="left" width="85%"> |
| <a href="javascript:toggle('ca');"> |
| Content assist |
| </a> |
| </td><td align="left"> |
| Moderate |
| </td></tr></table> |
| <div id="ca" style="display: none; margin-left: 32px;"> |
| <p> |
| Eclipse editors support <i>word completion</i> automatically; <i>content assist</i> is a |
| "smarter," context-sensitive variant of word completion. Although extremely sophisticated |
| variations are possible, only rudimentary support is required for this project. |
| <p> |
| This project has two parts and a bonus part which is optional but significantly more useful. |
| <i>Keep your code for each part. Each is useful for a different reason, and any or all could end up |
| in production (in one form or another).</i> |
| <ol> |
| <li> Prototype content assist. Demonstrate what is minimally required to implement content assist |
| in the editor: What classes have to be changed, and how? You can pop up any arbitrary list of |
| words (say, <tt>{ "Fill", "In", "This", "List" }</tt>). |
| <li> Collect a list of identifiers, and use it to fill in the list. |
| Use the editor's <i>partitioning</i> to collect this list |
| (this divides the text into regions for syntax highlighting, among other things). |
| </ol> |
| <p> |
| This can be implemented in the main Fortran editor(s)/<tt>AbstractFortranEditor</tt>. |
| <p> |
| <b>Bonus Points</b> (Difficulty: 4). |
| Use the VPG (and a <tt>DefinitionMap</tt>, which has the infrastructure you need) |
| to collect a list of all of the identifiers in a program and their associated scopes. |
| When the user activates content assist, show only those identifiers that are in scope at the |
| cursor position. |
| You will need to implement this in the <i>experimental</i> editor located in the |
| org.eclipse.photran.ui.vpg plug-in (when you run Photran, right-click a file and choose |
| Open With > Fortran Editor (VPG Experimental Features); "EXPERIMENTAL" should be displayed |
| in 36-point letters at the top of the editor window). The JavaDoc and sample code in the |
| org.eclipse.photran.internal.ui.editor_vpg package should be particularly helpful. |
| </div> |
| <li> <table border="0" cellspacing="0" cellpadding="0" width="75%"><tr><td nowrap align="left" width="85%"> |
| <a href="javascript:toggle('mp');"> |
| Matching parenthesis highlighting |
| </a> |
| </td><td align="left"> |
| Easy |
| </td></tr></table> |
| <div id="mp" style="display: none; margin-left: 32px;"> |
| <p> |
| If you know how to use Google and Edit > Paste, you can probably do this project |
| (although you should be very careful about intellectual property/licensing issues). |
| Still, it has been requested several times and will be immensely useful. |
| This should be used as a "warm up" project to get acquainted with the editor; if you do this, |
| you should also work on another project (such as the JDT-/CDT-style preference page and/or auto-indent). |
| </div> |
| <li> <table border="0" cellspacing="0" cellpadding="0" width="75%"><tr><td nowrap align="left" width="85%"> |
| <a href="javascript:toggle('ht');"> |
| Hover tips containing type/declaration |
| </a> |
| </td><td align="left"> |
| Moderate |
| </td></tr></table> |
| <div id="ht" style="display: none; margin-left: 32px;"> |
| <p> |
| If you hover your mouse over an identifier in JDT (or CDT), a tooltip window with the declaration |
| appears. This project would be to implement something similar for Fortran. You will need to decide |
| what to display in the hover tip, based on the type of identifier. |
| <p> |
| You will need to implement this in the <i>experimental</i> editor located in the |
| org.eclipse.photran.ui.vpg plug-in (when you run Photran, right-click a file and choose |
| Open With > Fortran Editor (VPG Experimental Features); "EXPERIMENTAL" should be displayed |
| in 36-point letters at the top of the editor window). The JavaDoc and sample code in the |
| org.eclipse.photran.internal.ui.editor_vpg package should be particularly helpful. |
| </div> |
| <li> <table border="0" cellspacing="0" cellpadding="0" width="75%"><tr><td nowrap align="left" width="85%"> |
| <a href="javascript:toggle('ai');"> |
| Auto-indent |
| </a> |
| </td><td align="left"> |
| Moderate |
| </td></tr></table> |
| <div id="ai" style="display: none; margin-left: 32px;"> |
| <p> |
| Eclipse editors auto-indent automatically (Photran currently uses this default auto-indent strategy), |
| but this behavior can be customized for particular languages. In the case of Fortran, the indentation |
| should be increased, for example, when the user presses Enter to complete a <tt>program</tt> statement, |
| and an <tt>end program</tt> statement should be un-indented automatically. (However, the line following |
| the assignment statement <tt>program = 3</tt> should <i>not</i> be auto-indented, so this is more |
| complex than looking at the first characters on the line.) |
| <p> |
| Customizing auto-indent in an Eclipse editor is fairly straightforward. The difficult part is |
| implementing it in such a way that it "feels natural" and is more useful than the default |
| auto-indent strategy. It is surprisingly easy to make an auto-indent strategy that is more annoying than |
| useful. So while this project is technically easy, a successful project will require some significant |
| usability testing (by "real" Fortran programmers); a half-working implementation will not |
| make it into production. |
| <p> |
| This can be implemented in the main Fortran editor(s)/<tt>AbstractFortranEditor</tt>. |
| The <i>partitioning</i> should be useful in helping determing when particular words (e.g., |
| <tt>program</tt> or <tt>if</tt>) are used as identifiers and when they are used as keywords, |
| an essential distinction for determining when to auto-indent.. |
| </div> |
| <li> <table border="0" cellspacing="0" cellpadding="0" width="75%"><tr><td nowrap align="left" width="85%"> |
| <a href="javascript:toggle('fold');"> |
| Folding |
| </a> |
| </td><td align="left"> |
| Easy |
| </td></tr></table> |
| <div id="fold" style="display: none; margin-left: 32px;"> |
| <p> |
| <i>Folding</i> is the ability to collapse several lines of text in the editor. |
| In JDT, for example, there is a plus sign in the left margin of the editor next to each method |
| definition: Clicking on this collapses that function into a single line. |
| <p> |
| This project has two parts: One is determining what constructs in the Fortran language should |
| be folded in the editor; the other is actually implementing this. |
| <p> |
| You will need to implement this in the <i>experimental</i> editor located in the |
| org.eclipse.photran.ui.vpg plug-in (when you run Photran, right-click a file and choose |
| Open With > Fortran Editor (VPG Experimental Features); "EXPERIMENTAL" should be displayed |
| in 36-point letters at the top of the editor window). The JavaDoc and sample code in the |
| org.eclipse.photran.internal.ui.editor_vpg package should be particularly helpful. |
| <p> |
| <b>Bonus Points.</b> |
| C# has a <tt>#region</tt> directive which can be placed around arbitrary sections of code to make them |
| foldable in the editor. Use Fortran comment lines (perhaps <tt>! region "Some summary text"</tt> |
| and <tt>! end region</tt>) to achieve a similar effect in Photran. (Hint: Comments are available in the |
| AST, but it is probably faster to scan the editor text line by line using a regular expression, e.g., |
| using Java's <tt>Pattern</tt> class, and the editor's <i>partitioning.</i>) |
| </div> |
| <li> <table border="0" cellspacing="0" cellpadding="0" width="75%"><tr><td nowrap align="left" width="85%"> |
| <a href="javascript:toggle('ref');"> |
| Find all references |
| </a> |
| </td><td align="left"> |
| Moderate |
| </td></tr></table> |
| <div id="ref" style="display: none; margin-left: 32px;"> |
| <p> |
| In JDT, clicking on Search > References provides several options for searching for all of the references |
| to a particular entity. (This is also available in the editor context menu.) The goal of this project |
| is to implement this in Fortran. At a minimum, a workspace-wide search should be implemented; |
| searching within a single project and/or working set should be attempted if time permits. |
| <p> |
| This will need to be implemented in the VPG UI plug-in. It is probably easiest to contribute |
| these actions to the <i>experimental</i> editor located in the |
| org.eclipse.photran.ui.vpg plug-in (when you run Photran, right-click a file and choose |
| Open With > Fortran Editor (VPG Experimental Features); "EXPERIMENTAL" should be displayed |
| in 36-point letters at the top of the editor window). The JavaDoc and sample code in the |
| org.eclipse.photran.internal.ui.editor_vpg package should be particularly helpful. Performing the |
| search itself is actually quite easy (Hint: Finding all of the references to a variable |
| is an essential part of performing a Rename refactoring). |
| </div> |
| <li> <table border="0" cellspacing="0" cellpadding="0" width="75%"><tr><td nowrap align="left" width="85%"> |
| <a href="javascript:toggle('search');"> |
| Prototype Fortran search |
| </a> |
| </td><td align="left"> |
| Moderate |
| </td></tr></table> |
| <div id="search" style="display: none; margin-left: 32px;"> |
| <p> |
| Both JDT and CDT have Search dialogs specific to their language, which allow you to search for |
| classes, methods, enums, and other types of constructs based on name. The goal of this project |
| is to prototype UI support for Fortran Search and to identify what can and cannot be done easily with |
| Photran's VPG. This project consists of the following parts. |
| <ol> |
| <li> Design and prototype a Fortran Search page, similar to the Java and C/C++ search pages. |
| What types of entities can be searched for in a Fortran program? |
| <li> Implement a search results page. <i>You do not need to actually perform the search |
| according to the criteria in the dialog box;</i> an arbitrary, fixed list of results is fine |
| (e.g., the first search result will always jump to line 5 in someproject/somefile.f90). |
| <li> The JDT and CDT both have a program database that is quite different from Photran's VPG. |
| Read the code that computes search results for JDT and CDT, and (in writing) briefly summarize |
| how search results are computed in these tools. How is regular expression matching performed? |
| What sort of API is provided by their program database to facilitate searching? |
| (Photran's VPG was not designed to facilitate searches like this; your "report" |
| from this section should help us identify what sort of API would need to be built to support |
| your search dialogs.) |
| </ol> |
| <p> |
| This will need to be implemented in the VPG UI plug-in. |
| <p> |
| <b>Bonus Points.</b> |
| Instead of a fixed, arbitrary list of search results, implement <i>some</i> search functionality using |
| the VPG. For example, you might perform the search specified by the user, but limit the search |
| to only one particular file (rather than attempting to perform it on an entire project or the entire |
| workspace). |
| </div> |
| <li> <table border="0" cellspacing="0" cellpadding="0" width="75%"><tr><td nowrap align="left" width="85%"> |
| <a href="javascript:toggle('pref');"> |
| JDT-/CDT-style preference page for editor coloring |
| </a> |
| </td><td align="left"> |
| Easy |
| </td></tr></table> |
| <div id="pref" style="display: none; margin-left: 32px;"> |
| <p> |
| Photran's preference page for setting editor colors is simple and functional; JDT and CDT have a |
| more sophisticated page which displays sample code to illustrate highlighting. Implement a similar |
| page for Photran. |
| <p> |
| This project, like matching parenthesis highlighting, is largely copy-and-paste, so you should |
| plan to work on another project as well. |
| </div> |
| <li> <table border="0" cellspacing="0" cellpadding="0" width="75%"><tr><td nowrap align="left" width="85%"> |
| <a href="javascript:toggle('docv');"> |
| Declaration view |
| </a> |
| </td><td align="left"> |
| Moderate |
| </td></tr></table> |
| <div id="docv" style="display: none; margin-left: 32px;"> |
| <p> |
| Create a Declaration view for Fortran (like the one in JDT). When the user's cursor is moved |
| over a subprogram identifier, display the declaration (function or subroutine statement) |
| and preceding comment for the referenced subprogram. |
| (Hint: Note that <tt>CSTNode#printOn(PrintStream)</tt> can be used to retrieve the exact text of an |
| AST node, including whitespace and comments.) |
| <p> |
| You will need to implement this in the <i>experimental</i> editor located in the |
| org.eclipse.photran.ui.vpg plug-in (when you run Photran, right-click a file and choose |
| Open With > Fortran Editor (VPG Experimental Features); "EXPERIMENTAL" should be displayed |
| in 36-point letters at the top of the editor window). The JavaDoc and sample code in the |
| org.eclipse.photran.internal.ui.editor_vpg package should be particularly helpful. |
| </div> |
| <li> <table border="0" cellspacing="0" cellpadding="0" width="75%"><tr><td nowrap align="left" width="85%"> |
| <a href="javascript:toggle('complain');"> |
| Complain about Photran (two sub-projects) |
| </a> |
| </td><td align="left"> |
| Moderate |
| </td></tr></table> |
| <div id="complain" style="display: none; margin-left: 32px;"> |
| <p> |
| We might regret this later... this project will make it easy for users to complain about Photran. |
| <ul> |
| <li> Contribute a Photran menu to menu bar in the Fortran perspective and the Fortran editors |
| with the following items. |
| <ul> |
| <li> <i>Send a Complaint About Photran.</i> This will pop up a dialog box where the user can |
| describe a problem they are having with Photran (e.g., it is running out of memory). |
| They should supply their name and e-mail address. Their operating system, Eclipse version, |
| Photran version, JVM, and similar information should be collected automatically. |
| <li> <i>Submit Code that Highlights Incorrectly.</i> This will allow the user to submit the |
| contents of the active editor. |
| The fields in the above item (name, e-mail, OS, etc.) should be included as well. |
| <li> <i>Submit Code that Does Not Parse But Should.</i> This will allow the user to submit the |
| contents of the active editor so that we can add it to our suite of parser tests. |
| The fields in the above item (name, e-mail, OS, etc.) should be included as well, |
| although no comments are necessary (we can figure out the parse error on our own). |
| It should be verified that the file does not parse; sometimes users confuse syntax highlighting |
| with parsing. |
| <li> (Put a separator in the menu at this point.) |
| <li> <i>View Frequently Asked Questions.</i> This simply opens a browser window on the Photran FAQ. |
| <li> <i>View Photran Web Site.</i> This opens a browser window on http://www.eclipse.org/photran |
| </ul> |
| <li> The first three menu items above should submit the information to a script on Photran's web |
| server (see next item). |
| <li> (No Java!) Create a PHP script which can run on Photran's web site and accept these submissions |
| from Photran clients. It should then e-mail the information to an address we will give you. |
| This should be easy to customize; we might eventually modify it to automatically generate a |
| JUnit test and a CVS patch, for example. |
| </ul> |
| <p> |
| There are lots of ways to communicate the data between Photran and the Web server (a simple HTTP POST |
| or XML-RPC, among others). Be prepared to defend your choice on technical grounds. "We wanted |
| to try this" is not a good justification. |
| <p> |
| The PHP work will be heavily scrutinized for security holes. Eclipse.org is a prominent, high-traffic |
| site; running risky or questionable scripts on their servers is unacceptable. |
| </div> |
| </ul> |
| |
| <h2>Refactorings & Transformations</h2> |
| <p>Difficulty ratings for these projects assume that you have a basic knowledge of abstract syntax trees |
| and other concepts from an introductory programming languages/compilers course. If you do not, these projects |
| probably aren't appropriate.</p> |
| <ul> |
| <li> <table border="0" cellspacing="0" cellpadding="0" width="75%"><tr><td nowrap align="left" width="85%"> |
| <a href="javascript:toggle('cancapid');"> |
| Canonicalize Identifier Capitalization |
| </a> |
| </td><td align="left"> |
| Easy |
| </td></tr></table> |
| <div id="cancapid" style="display: none; margin-left: 32px;"> |
| <p> |
| This is essentially a variant of a Rename refactoring. |
| <ul> |
| <li> The user should be able to select whether to apply the refactoring to a particular identifier |
| or all of the identifiers in a scope. This will determine what <tt>Definition</tt> |
| objects the refactoring will apply to. |
| <li> For each <tt>Definition</tt>, all of the references are modified so that their capitalization |
| matches that of the declaration. |
| </ul> |
| <p> |
| This is an easy project, so you should plan to work on another project as well. |
| <p> |
| Code from both the Rename and Introduce Implicit None refactorings will be useful in implementing |
| this refactoring. |
| </div> |
| <li> <table border="0" cellspacing="0" cellpadding="0" width="75%"><tr><td nowrap align="left" width="85%"> |
| <a href="javascript:toggle('cancapkw');"> |
| Canonicalize Keyword Capitalization |
| </a> |
| </td><td align="left"> |
| Moderate |
| </td></tr></table> |
| <div id="cancapkw" style="display: none; margin-left: 32px;"> |
| <p> |
| This is more of a code style modification than a refactoring. |
| <ul> |
| <li> The user should be able to select whether to apply the refactoring to a selected statement or |
| range of statements, a particular scope, or an entire file. (It would be nice to be able to |
| apply this to all of the files in a folder or project, but that is not required.) |
| <li> The user should be able to decide whether to convert keywords to upper- or lowercase. |
| <li> All of the keywords in the selected region are capitalized accordingly. |
| </ul> |
| <p> |
| The Rename refactoring contains code that will be useful in implementing |
| this refactoring. |
| </div> |
| <li> <table border="0" cellspacing="0" cellpadding="0" width="75%"><tr><td nowrap align="left" width="85%"> |
| <a href="javascript:toggle('alignid');"> |
| Align Identifiers in Declarations |
| </a> |
| </td><td align="left"> |
| Challenging |
| </td></tr></table> |
| <div id="alignid" style="display: none; margin-left: 32px;"> |
| <p> |
| This is more of a code style modification than a refactoring. |
| Fortran programmers commonly begin subprograms with lists of type declarations in which they align |
| variable names and trailing comments (if any). For example, |
| <pre> |
| subroutine s |
| implicit none |
| integer, parameter :: three = 3 ! A constant |
| real :: matrix(256,256) ! The decryption matrix |
| character(len=*) :: message = "Decryption failed" |
| </pre> |
| This refactoring simply aligns the double-colons (if any), variable names, and trailing |
| comments (if any) as shown. |
| <ul> |
| <li> The user must select the scope for which the refactoring will be applied. |
| Other user-customizable options are possible but not necessary |
| (for example, they could toggle whether double-colons, variable names, and/or |
| comments are aligned). |
| <li> Identify all of the type declaration statements for that scope. |
| Compute the starting columns and lengths of each part of each statement, |
| and use the maximums to determine what columns to align on. (Hint: |
| Use <tt>CSTNode#printOn</tt> to determine the user's exact text for a |
| particular node in the AST.) Note that there may be line continuations |
| in these statements; you can decide how to deal with those. |
| <li> For each statement, insert spaces as needed to align tokens in the desired |
| columsn. (Note that <tt>Token</tt> objects contain the token text as well |
| as preceding and trailing whitespace and comments ("whitetext"); |
| these whitetext properties can be modified to perform the alignment.) |
| </ul> |
| <p> |
| The Rename and Introduce Implicit None refactorings contain code that will be useful in implementing |
| this refactoring. |
| </div> |
| <li> <table border="0" cellspacing="0" cellpadding="0" width="75%"><tr><td nowrap align="left" width="85%"> |
| <a href="javascript:toggle('elimspec');"> |
| Eliminate Specification Statements |
| </a> |
| </td><td align="left"> |
| Very Challenging |
| </td></tr></table> |
| <div id="elimspec" style="display: none; margin-left: 32px;"> |
| <p> |
| In Fortran, attributes such as dimension, intent, etc. can be specified in the type declaration |
| statement for a variable, or they can be given in separate specification statements. |
| This refactoring eliminates these specification statements, moving all of these attributes into |
| the type declaration statement. |
| <ul> |
| <li> The user should be able to select whether to apply the refactoring to a particular identifier |
| or all of the identifiers in a scope. |
| <li> Every identifier must have an existing type declaration statement into which these attributes |
| can be moved. (If not, the user should run the Introduce Implicit None refactoring first.) |
| The type declaration statement must be in the same scope as the specification statement. |
| <li> The existing type declaration statement must not have a clause which conflicts with a |
| specification statement. For example, it is illegal to specify the dimension of an array |
| in both the type declaration statement and in a separate <tt>dimension</tt> statement. |
| Also, there must not be two or more conflicting specification statements (e.g., two |
| <tt>dimension</tt> statements for the same variable). |
| <li> Specification statements are removed and equivalent clauses inserted into the |
| type declaration statement(s) for the affected variables(s). |
| </ul> |
| <p> |
| Before implementing this refactoring, you will need to identify (1) what the various specification |
| statements are and (2) what the equivalent type declaration clauses are. (Are there any specification |
| statements which can't be eliminated?) Then you will be able to (1) specify |
| in detail what it means for a specification statement to be in conflict with another specification |
| statement or a type declaration clause, and (2) specify exactly what text must be added to a |
| type declaration statement (and where) to preserve semantics after the specification statement |
| has been removed. |
| <p> |
| Code from both the Rename and Introduce Implicit None refactorings will be useful in implementing |
| this refactoring. |
| </div> |
| <!--li> <table border="0" cellspacing="0" cellpadding="0" width="75%"><tr><td nowrap align="left" width="85%"> |
| <a href="javascript:toggle('com2mod');"> |
| Move Common Variable Into Module |
| </a> |
| </td><td align="left"> |
| Very Challenging |
| </td></tr></table> |
| <div id="com2mod" style="display: none; margin-left: 32px;"> |
| <p> |
| TODO: To do this right, we need to analyze all of the common blocks program-wide, and make sure |
| they have the same structure. That could get nasty... |
| </div--> |
| <li> <table border="0" cellspacing="0" cellpadding="0" width="75%"><tr><td nowrap align="left" width="85%"> |
| <a href="javascript:toggle('mod2mod');"> |
| Move Variable/Procedure Between Modules |
| </a> |
| </td><td align="left"> |
| Very Challenging |
| </td></tr></table> |
| <div id="mod2mod" style="display: none; margin-left: 32px;"> |
| <p> |
| <ul> |
| <li> The user should select an identifier and a target module into which that variable/procedure |
| should be moved. The target module must be different from the source module. |
| <li> The variable/procedure must not have private visibility. |
| <li> The target module must not contain an entity with the same (canonicalized) name as the |
| variable/procedure to move. |
| <li> If an enclosing scope for the target module contains an entity with the same |
| (canonicalized) name as the variable/procedure to move, then all of the references to that |
| entity must still resolve to that entity even if the moved variable/procedure will shadow |
| it within the scope of the module. (Hint: This check is done in the Rename refactoring.) |
| <li> Consider each scope which imports the target module. |
| <ul> |
| <li> If that scope also imports the source module but does <i>not</i> import the |
| variable/procedure being moved (due to an <tt>only</tt> list)... |
| <ul> |
| <li> If there is <tt>only</tt> list on the <tt>use</tt> statement for the target |
| module, no action needs to be taken. If there is <i>not</i> an <tt>only</tt> |
| list for the target module... |
| <ul> |
| <li> If the scope containing the <tt>use</tt> statement or an enclosing |
| scope contains an entity with the same |
| (canonicalized) name as the variable/procedure to move, then all of the references to that |
| entity must still resolve to that entity even if the moved variable/procedure will shadow |
| it within the scope of the module. (Hint: This check is done in the Rename refactoring.) |
| If they do not, an <tt>only</tt> list must be appended to the <tt>use</tt> |
| statement for the target module, which explicitly imports all of the publically-visible |
| members of the target module (not including the variable/procedure being moved). |
| <li> Otherwise, no action needs to be taken: Importing the moved variable/procedure |
| into this scope will have no effect. |
| </ul> |
| </ul> |
| <li> If that scope does not import the source module... |
| <ul> |
| <li> If the scope or an enclosing |
| scope contains an entity with the same |
| (canonicalized) name as the variable/procedure to move, then all of the references to that |
| entity must still resolve to that entity even if the moved variable/procedure will shadow |
| it within the scope of the module. (Hint: This check is done in the Rename refactoring.) |
| If they do not, an <tt>only</tt> list must be appended to the <tt>use</tt> |
| statement for the target module, which explicitly imports all of the publically-visible |
| members of the target module (not including the variable/procedure being moved). |
| <li> Otherwise, no action needs to be taken: Importing the moved variable/procedure |
| into this scope will have no effect. |
| </ul> |
| </ul> |
| <li> Consider each reference to the variable/procedure in the source module. |
| There must be a <tt>use</tt> statement which imports the source module. There may or may |
| not be a <tt>use</tt> statement which imports the target module, |
| <ul> |
| <li> If there is no <tt>use</tt> statement for the target module, a statement of the |
| form <tt>use targetmodule, only: identifier</tt> must be added, preferably immediately |
| below the <tt>use</tt> statement for the source module. |
| <li> If there is already a <tt>use</tt> statement for the target module, and there is |
| an <tt>only</tt> list, the variable/procedure must be added to that list. |
| <li> If the <tt>use</tt> statement for the source module includes an <tt>only</tt> list, |
| the variable/procedure being imported must be included in this list, and that clause |
| must be removed. |
| <li> If the <tt>use</tt> statement for the source module renames the variable/procedure, |
| the rename clause must be removed from that <tt>use</tt> statement, and an identical |
| rename clause must be added to the <tt>use</tt> statement for the target module. |
| </ul> |
| </ul> |
| <p> |
| Code from both the Rename and Introduce Implicit None refactorings will be useful in implementing |
| this refactoring. |
| </div> |
| <li> <table border="0" cellspacing="0" cellpadding="0" width="75%"><tr><td nowrap align="left" width="85%"> |
| <a href="javascript:toggle('ralph');"> |
| Make Common Variable Names Consistent |
| </a> |
| </td><td align="left"> |
| Challenging |
| </td></tr></table> |
| <div id="ralph" style="display: none; margin-left: 32px;"> |
| <p> |
| "COMMON" is a kind of global variable that dates from the earliest |
| versions of Fortran. Often they should be replaced by module |
| variables, and even if they should remain COMMON variables, they |
| should follow certain rules. |
| <p> |
| A COMMON block has a name (there is also an unnamed COMMON block) |
| and a list of variables. Different modules, procedures, etc. |
| can use the variables in that COMMON block by giving its name and the list of |
| variables. Different specifications of a COMMON block do not have to |
| list the same variables in the same order. |
| <p> |
| For example, suppose we have a program |
| <pre> |
| program main |
| integer :: a, b |
| real :: c |
| common /d/ a, b, c |
| ... |
| end main |
| </pre> |
| This defines a common block named "d" with three variables. |
| <p> |
| Suppose we also have a subroutine |
| <pre> |
| subroutine proc(x,y) |
| integer :: a,b, x, y |
| real :: c |
| common /d/ a, b, c |
| ... |
| end subroutine proc |
| </pre> |
| Variable a in "main" is the same memory location as variable a in |
| "proc". This is a kind of global variable where you have to |
| explicitly state that a subroutine uses the variable. At first, it |
| seems not as bad as regular global variables. But it is actually |
| worse! |
| <p> |
| Suppose that the subroutine proc was defined as follows: |
| <pre> |
| subroutine proc(a,b) |
| integer :: a,b, x, y |
| real :: c |
| common /d/ x, y, c |
| ... |
| end subroutine proc |
| </pre> |
| This program would behave the same as the previous one (i.e. it is a |
| refactoring) except that the variable called "a" in "main" is called |
| "x" in subroutine "proc". The program might be correct for awhile, |
| but someone is likely to cut an expression using a and b from one part |
| of the program to the other, and cause a bug, because "a" in one part |
| is not "a" in the other. |
| <p> |
| Even worse, consider the definition |
| <pre> |
| subroutine proc(x,y) |
| integer :: a,b, x, y |
| real :: c |
| common /d/ b, c |
| </pre> |
| Now, "b" is the same as "a" in "main", and "c" is not the same as "c". |
| "c" in "proc" overlaps in memory with "b" in "main", but an integer |
| is probably 32 bits while a real is probably 128 bits, so everything |
| will be thrown off. In fact, it is possible to do useful tricks, like |
| having an array of length 10 in one definition of a common block, and |
| then having ten variables in the other. This trick is portable. |
| However, if you decide to have four integer variables in one COMMON |
| definition match a real variable in another, so you can break a 128 |
| bit real number into four 32 bit ints, the code is not portable. |
| <p> |
| First, we need to be able to find every use of a COMMON block and to |
| check that they are all the same. Often, people INCLUDE the COMMON |
| block definition to make sure that they are all the same. Sometimes |
| people make them different on purpose. Ick! There should be a way to |
| rename variables to make them the same if the problem can be solved by |
| a simple renaming. |
| <!-- |
| If we are using Fortran 90, we should move all the code that access a |
| COMMON block to a single module. Then we can get rid of the common |
| block and make the variables be module variables. |
| --> |
| <p> |
| See |
| <a href="http://www.sesp.cse.clrc.ac.uk/Publications/Legacy-Software/Legacy-Software/node8.html"> |
| http://www.sesp.cse.clrc.ac.uk/Publications/Legacy-Software/Legacy-Software/node8.html |
| </a> |
| <p> |
| Here is a great discussion of IMPLICIT NONE |
| <a href="http://www.sesp.cse.clrc.ac.uk/Publications/Legacy-Software/Legacy-Software/node11.html"> |
| http://www.sesp.cse.clrc.ac.uk/Publications/Legacy-Software/Legacy-Software/node11.html |
| </a> |
| <p> |
| The top of this interesting report on maintaining Fortran code is at |
| <a href="http://www.sesp.cse.clrc.ac.uk/Publications/Legacy-Software/Legacy-Software/legacy.html"> |
| http://www.sesp.cse.clrc.ac.uk/Publications/Legacy-Software/Legacy-Software/legacy.html |
| </a> |
| </div> |
| </ul> |
| |
| <h2>Static Analyses</h2> |
| <ul> |
| <li> <table border="0" cellspacing="0" cellpadding="0" width="75%"><tr><td nowrap align="left" width="85%"> |
| <a href="javascript:toggle('en');"> |
| Enforcement of naming conventions |
| </a> |
| </td><td align="left"> |
| Challenging |
| </td></tr></table> |
| <div id="en" style="display: none; margin-left: 32px;"> |
| <p> |
| <ul> |
| <li> Create either a global preference page or a project property page which allows the user to |
| provide regular expressions for (1) local variables and subprogram parameter names, |
| (2) subprogram names, and (3) module names. In the first case, provide the option to provide |
| a different regex for each type (integer, real, complex, etc.) |
| <li> Add an action to the menu bar which will check if the file in the editor meets these naming |
| conventions. (Essentially, find all of the <tt>Definition</tt>s in the file, and compare |
| their names against the appropriate regular expression provided by the user.) |
| Ideally, you should use <i>markers</i> to identify the problematic names in the editor. |
| </ul> |
| <p> |
| <b>Bonus Points.</b> Implement this functionality in a <i>builder.</i> |
| </div> |
| </ul> |
| |
| <!--h2>Doxygen Support</h2> |
| <ul> |
| <li> <table border="0" cellspacing="0" cellpadding="0" width="75%"><tr><td nowrap align="left" width="85%"> |
| <a href="javascript:toggle('gstub');"> |
| Generate Doxygen stubs |
| </a> |
| </td><td align="left"> |
| 4 |
| </td></tr></table> |
| <div id="gstub" style="display: none; margin-left: 32px;"> |
| <p> |
| <ul> |
| <li> The user should highlight a function or subroutine definition in the editor. |
| <li> Identify the parameter names and types and, in the case of functions, the return type. |
| </ul> |
| </div> |
| <li> <table border="0" cellspacing="0" cellpadding="0" width="75%"><tr><td nowrap align="left" width="85%"> |
| <a href="javascript:toggle('doxv');"> |
| Doxygen view and Doxygen checking (requires parser) |
| </a> |
| </td><td align="left"> |
| ? |
| </td></tr></table> |
| <div id="doxv" style="display: none; margin-left: 32px;"> |
| </div> |
| <li> <table border="0" cellspacing="0" cellpadding="0" width="75%"><tr><td nowrap align="left" width="85%"> |
| <a href="javascript:toggle('gdox');"> |
| "Generate Doxygen" action |
| </a> |
| </td><td align="left"> |
| ? |
| </td></tr></table> |
| <div id="gdox" style="display: none; margin-left: 32px;"> |
| </div> |
| </ul--> |
| |
| <h2>Large Test Codes (3+ Projects)</h2> |
| |
| <p> |
| <a href="javascript:toggle('test');"> |
| Project Description |
| </a> |
| <b>(Difficulty: Easy)</b> |
| </p> |
| |
| <div id="test" style="display: none; margin-left: 32px;"> |
| Photran's parser has been tested on several programs, including a commercial test suite, but it still has bugs. |
| Also, many other features (most notably the VPG) have not yet been optimized for scalability. |
| For both of these reasons, we need to create Photran projects for several large, well-known Fortran programs. |
| <p> |
| Choose one (or more) of the programs listed below, and do the following. |
| <ul> |
| <li> Build and run the program. You must be able to do this successfully; if it turns out that you do not |
| have the required hardware or software, you will need to find a different project to work on, so do |
| this immediately. Chances are good you will need to use Linux. |
| <li> Write a brief report which includes the following. |
| <ul> |
| <li> Summarize what the program does, at a high level (in a paragraph or two). |
| <li> What dialect(s) of Fortran it's written in (Fortran 66, 77, 90, 95, 2003, HPF, etc.). |
| Some programs use vendor-specific extensions as well (Cray pointers, %val/%ref in Intel Fortran, etc.) |
| <li> Whether its source is free form, fixed form, or both, and what filename extensions are used for each. |
| <li> Whether it requires any third-party libraries that are not included (e.g., BLAS, LAPACK, MPICH). |
| Indicate the dialect, source form, filename extensions, etc. of these libraries as well. |
| <li> Whether the entire program is written in Fortran or whether it has modules written in other languages |
| (most likely C or C++). |
| <li> Whether it uses the C preprocessor or other preprocessing mechanisms. (Flash/IBEAM uses Python |
| in its build process, for example.) |
| <li> How to build the program (in detail). Indicate specifically what tools you used (including version |
| numbers) and on what platform. Is the build process based on GNU Make? |
| </ul> |
| <li> Run Photran, and import this code into a Standard Make project. You should be able to build and run |
| the project from inside Photran. If it does not use <tt>make</tt> for its build process, you should |
| create a dummy Makefile which delegates to the custom build tool, or be able to explain why this is not |
| possible. |
| <li> Change the filename extension associations accordingly if it does not use Photran's defaults. |
| <li> Zip up your workspace and submit it so that we can integrate it into the test suite at a later date. |
| <li> Create a JUnit Plug-in Test which (programmatically) attempts to parse a couple of interesting source |
| files from that program. The Run dialog (Run > Open Run Dialog) allows you to specify what workspace |
| the test will be run in, and whether or not to clear (delete the contents of) that workspace when the |
| test is run. When you run your test, you can use your workspace as its runtime workspace (make sure |
| <i>not</i> to clear it before running!); then you can programmatically get access to the individual |
| files (starting from <tt>ResourcesPlugin.getWorkspace().getRoot()</tt>). |
| <li> If your test fails, why? Is the file not legal Fortran (e.g., it needs to be preprocessed first)? |
| Is Photran's parser just broken? Be able to explain this. |
| </ul> |
| </div> |
| <ul> |
| <li> <a href="http://climate.lanl.gov/Models/POP/">Parallel Ocean Program</a> |
| <li> <a href="http://www.emsl.pnl.gov/docs/nwchem/nwchem.html">NWChem</a> |
| <li> <a href="http://www.nsf.gov/pubs/2006/nsf0605/nsf0605.jsp">NSF Scientific Application Benchmarks</a>, |
| most notably WRF and GAMESS (see Section 3.0) |
| <li> Various codes listed at <a href="http://g95.sourceforge.net/g95_status.html">http://g95.sourceforge.net/g95_status.html</a> |
| <li> LANL has several other codes, but some are export-controlled. If you are interested, we can discuss this. |
| </ul> |
| </div> |
| |
| </div> |
| </div> |
| EOHTML; |
| |
| # Generate the web page |
| $App->generatePage($theme, $Menu, $Nav, $pageAuthor, $pageKeywords, $pageTitle, $html); |
| ?> |