blob: b62579c0ca756215579aab47698a2261106569b9 [file] [log] [blame]
<?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 as a Photran Contributor</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 &quot;perspectives&quot; and &quot;views&quot; 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 &quot;Hello, world!&quot; 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 &amp; 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 &quot;easy&quot; means &quot;easy relative to some other projects,&quot; not &quot;any CS1 student
could do this project.&quot; 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 &gt; Fortran Editor (VPG Experimental Features); &quot;EXPERIMENTAL&quot; 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
&quot;smarter,&quot; 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 &gt; Fortran Editor (VPG Experimental Features); &quot;EXPERIMENTAL&quot; 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 &gt; 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 &quot;warm up&quot; 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 &gt; Fortran Editor (VPG Experimental Features); &quot;EXPERIMENTAL&quot; 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 &quot;feels natural&quot; 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 &quot;real&quot; 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 &gt; Fortran Editor (VPG Experimental Features); &quot;EXPERIMENTAL&quot; 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 &gt; 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 &gt; Fortran Editor (VPG Experimental Features); &quot;EXPERIMENTAL&quot; 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 &quot;report&quot;
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 &gt; Fortran Editor (VPG Experimental Features); &quot;EXPERIMENTAL&quot; 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. &quot;We wanted
to try this&quot; 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 &amp; 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 (&quot;whitetext&quot;);
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.
<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');">
&quot;Generate Doxygen&quot; 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 &gt; 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>
-->
<ol>
<li> <b>Check out Photran's source code from CVS and run the test suite.</b>
We have written detailed
<a target="_blank" href="http://dev.eclipse.org/viewcvs/index.cgi/%7Echeckout%7E/org.eclipse.ptp/photran/org.eclipse.photran-dev-docs/dev-guide/cvs-instructions.pdf?cvsroot=Tools_Project">instructions</a>
on how to do this.
<li> <b>Join the <a target="_blank" href="https://dev.eclipse.org/mailman/listinfo/photran-dev">photran-dev mailing list</a>.</b>
This is where discussions about Photran's development take place.
Questions from developers (like you), release planning, API changes,
etc. all get discussed here.
<li> <b>Join the <a target="_blank" href="https://dev.eclipse.org/mailman/listinfo/photran">photran users' mailing list</a>.</b>
It is good to keep track of what Photran's users are discussing, and
as a Photran developer you will probably be able to answer many of
their questions as well.
<li> <b>Create a Bugzilla account.</b>
You will need to
<a target="_blank" href="https://bugs.eclipse.org/bugs/createaccount.cgi">create an account at bugs.eclipse.org</a>
if you don't already have one. When you eventually want to contribute
code to Photran, you will need to do it by attaching a patch to a
Bugzilla bug.
<li> <b>Read the <a target="_blank" href="http://dev.eclipse.org/viewcvs/index.cgi/%7Echeckout%7E/org.eclipse.ptp/photran/org.eclipse.photran-dev-docs/dev-guide/dev-guide.pdf?cvsroot=Tools_Project">Photran
Developer's Guide</a>.</b> Chapters 1, 2, and 3 apply to everyone.
The other chapters are more specialized; for example, the chapters
on Parsing and Refactoring only apply to people developing refactorings,
and the Photran Editors chapter applies mostly to people adding
features to the Fortran editor.
<li> <b>Get a book or two on Eclipse plug-in development.</b>
Eventually, you'll want to buy (or check out from the library) a book
on Eclipse plug-in development. I like <i>The Java Developer's Guide
to Eclipse</i> by D'Anjou et al., but there are other good ones as well.
If you get D'Anjou's book, you only need to read Chapters 7-9 and
possibly 21 to get started. After you figure out the basics of
Eclipse development (like how plugin.xml works), it's easiest to just
start fixing bugs or adding features, returning to it as a reference
when you have something more specific you need to do.
</ol>
<p>Photran's web site is
<a target="_blank" href="http://www.eclipse.org/photran">http://www.eclipse.org/photran</a>.
All of the above resources are listed on the &quot;Internals&quot; page.
</div>
</div>
</div>
EOHTML;
# Generate the web page
$App->generatePage($theme, $Menu, $Nav, $pageAuthor, $pageKeywords, $pageTitle, $html);
?>