Revision as of 14:12, 19 July 2009

You are here: PTP > Photran > Documentation > Photran 5.0 User's Guide

Photran 5.0 User's Guide

IMPORTANT: For the time being, this is just an outline of the documentation we intend to write before the release of Photran 5.0 in September, 2009. It is not useful yet. Of course, you are welcome to fill in any sections you wish... this is a wiki!

Installing Photran

System Requirements

To install Photran 5.0...

You must have Eclipse 3.5 (Galileo) installed.

1. You should have the C/C++ Development Tools (CDT) 6.0 installed. If you do not, they will be installed automatically when you install Photran.
2. Eclipse must be running on a Java 1.5 or later Java Virtual Machine (JVM). To get reasonable performance, we recommend Sun's JVM [1] or IBM's [2]. GNU Classpath (the default JVM on Fedora Linux) is generally too slow to be useful.
3. If you want to compile and build Fortran applications, you must have a make utility and a Fortran compiler in your system path. Many Linux/Unix systems include these; details on installing them in Windows and Mac are below.

Installation Procedure

To install Photran, start Eclipse, then...

1. Download the latest Photran zip file from [3]
2. Click on Help > Software Updates...
3. Click on the "Available Software" tab
4. Click on "Add Site..."
5. Click Archive...
6. Choose the zip file you downloaded from [4]
7. Click OK to close the Add Site dialog
8. The zip file should appear in the list as jar:file:/path/to/photran-master-4.0.5-something. Expand it.
9. Expand "Photran (Eclipse Fortran Development Tools)" and check the box next to "Photran (Eclipse Fortran Development Tools)"
10. If you are running Linux and have the Intel Fortran Compiler installed, or if you are on a Macintosh and have the IBM XL Fortran compiler installed, expand "Photran Compiler Support" and select the appropriate compiler.
11. Click on the "Install..." button in the upper-right corner of the dialog box.

Additional Instructions for Windows Users

To compile and run Fortran programs in Photran, you will need to have a Fortran compiler and make utility installed. Most Linux/Unix distributions include these; gfortran is commonly used (and free). Under Windows, you will need to install Cygwin [5] or MinGW [6] and put them on your Windows PATH.
Instructions for Cygwin:

1. Install [Cygwin http://www.cygwin.com/]; the defaults are mostly OK, but you will need to explicitly tell it to include the "Devel" packages (at least gcc4-fortran, gdb, and make) when the installer asks you to select what packages to install. (If gcc4-fortran is not listed under the "Devel" packages, you may have chosen a bad mirror; restart the Cygwin installation, and choose a different mirror instead. Georgia Tech's mirror at gtlib.gatech.edu is generally quite fast and reliable, for example.)
2. Add the Cygwin directories to your Windows PATH. Under Windows XP, the process is as follows:
   1. Make sure you are logged in under an administrator account.
   2. Open the Control Panel.
   3. Double-click the System icon.
   4. Switch to the Advanced tab.
   5. Click the Environment Variables button.
   6. Under System Variables, find the variable "Path" in the list, and click on it.
   7. Click Edit.
   8. At the end of the "Variable Value" text, add

      ;C:\Cygwin\bin;C:\Cygwin\usr\bin;C:\Cygwin\usr\local\bin;C:\Cygwin\lib;C:\Cygwin\usr\lib

   9. Click OK, click OK, click OK, and close the Control Panel.
   10. Close and re-open Photran. Windows should now search C:\Cygwin\bin, C:\Cygwin\usr\bin, etc. when it's looking for executables (including make.exe, gcc.exe, and gfortran.exe).

Additional Instructions for Mac OS X Users

If you install gfortran on Mac OS X, it may be installed in /usr/local/bin, which is not (by default) on the PATH. If you are launching Eclipse from a Terminal, the PATH can be set by modifying /etc/paths. However, if you are launching Eclipse from the Finder (by double clicking on it) or the Dock, then the PATH is not obtained from the shell or /etc/paths. Instead, it's obtained from ~/.MacOSX/environment.plist. The format of the environment.plist file is as follows (change the path appropriately). If you create or edit this file, you will need to log out (or reboot) before the changes will take effect.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>PATH</key>
    <string>/usr/local/mpi/bin:/usr/local/bin:/bin:/sbin:/usr/bin:/usr/sbin:/sbin:/usr/sbin:/Developer/Tools:/usr/texbin:/Users/greg/bin</string>
</dict>
</plist>

Starting a New Project

TODO
For more information, click on Help > Help Contents in Eclipse, and navigate to C/C++ Development User Guide > Concepts > CDT Projects.

Starting a Project with an Auto-Generated Makefile

TODO
If your system has the GNU gfortran compiler installed, try this.

1. Click File | New | Fortran Project
2. Call it whatever
3. Choose the Executable (Gnu Fortran) from the project type list
4. Choose GCC Toolchain from the toolchain list (you may need to uncheck the "Show project types..." check box at the bottom of the window)
5. Click Next
6. Click on Advanced Settings
7. Expand C/C++ Build in the list on the left, and click on Settings
8. Click on the Binary Parsers tab.  Check the appropriate parsers for your platform. If you are using Windows, check PE Windows Parser and/or Cygwin PE Parser; if you are using Linux, check Elf Parser; if you are using Mac, check Mach-O parser.
9. Click on the Error Parsers tab. Check the error parser(s) for the Fortran compiler(s) you will use.
10. Click OK
11. Click Finish
12. Click File | New | Source File
13. Call it hello.f90; click Finish
14. Type the standard "Hello, World" program, and click File | Save.

program hello
    print *, "Hello World"
end program

1. Open the Console view, and make sure "make" ran OK and compiled your program
2. In the Fortran Projects view, expand the Binaries entry, and click on your executable (e.g., "whatever - [x86le]")
3. Run | Run As | Run Local C/C++ Application (yeah, I know, it should say "Fortran Application", but it doesn't)
4. Choose GDB Debugger (Cygwin GDB Debugger if you're under Windows)
5. Check the Console view, and make sure Hello World appeared.

Starting a Project with a Hand-Written Makefile

TODO
If you're under Windows, make sure you have installed Cygwin (or MinGW) according to the installation instructions above.

1. File | New | Fortran Project
2. Call it whatever
3. Expand "Makefile project" in the project type list (it has a folder icon), and choose Empty Project
4. Make sure "-- Other Toolchain --" is selected in the toolchain list in the right-hand column, and click Next
5. Click on Advanced Settings
6. Expand C/C++ Build in the list on the left, and click on Settings
7. Click on the Binary Parsers tab.  Check the appropriate parsers for your platform. If you are using Windows, check PE Windows Parser and/or Cygwin PE Parser; if you are using Linux, check Elf Parser; if you are using Mac, check Mach-O parser.
8. Click on the Error Parsers tab. Check the error parser(s) for the Fortran compiler(s) you will use.
9. Click OK
10. Click Finish
11. File | New | File
12. Call it Makefile
13. Click Finish
14. We assume you're familiar with how to format a Makefile.  Something like this will work for now. 

Remember to start the g95 line with a tab, not spaces.  The -g switch instructs g95 to include debugging symbols in the generated executable so that it can be debugged later.

all:
        g95 -g hello.f90
clean:

1. File | New | Source File
2. Call it hello.f90
3. Click Finish
4. Type the standard "Hello, World" program.

program hello
    print *, "Hello World"
end program

1. Project | Clean; then click OK
2. Open the Console view, and make sure "make" ran OK and compiled your program
3. In the Fortran Projects view, expand the Binaries entry, and click on your executable (e.g., "whatever - [x86le]")
4. Run | Run As | Run Local C/C++ Application (yeah, I know, it should say "Fortran Application", but it doesn't)
5. Choose GDB Debugger (Cygwin GDB Debugger if you're under Windows)
6. Check the Console view, and make sure Hello World appeared.

Writing Code

The Fortran Perspective

If you are not already familiar with opening other views in your current perspective, you will find the following list from the Eclipse help guide helpful.

Selecting / Opening Views:

• You can add views to a perspective. From the menu bar choose Window > Show View > Other and select a new view from the Show View dialog.
• To reset the current perspective to its original layout, from the menu bar choose Window > Reset Perspective.

Fortran Perspective By default, the Fortran perspective contains an editor and the following views:

• Project Explorer
• Navigator
• Console
• Problems
• Fortran Declaration
• Outline Make Targets

Debug Perspective The debug perspective contains an editor area and the following views:

• Debug
• Variables
• Breakpoints
• Registers
• Modules
• Outline
• Console
• Tasks
• Problems
• Executables
• Memory

The Fortran Projects View

The Fortran Projects view displays project files in a tree structure. In this view you can do the following:

• Browse the elements of Fortran files
• Open files in the editor view
• Open projects in a new window
• Create new projects, files, or folders
• Manage existing files (cut, paste, delete, move or rename)
• Import or Export files and projects

Files that you select in the Fortran Projects view affect the information that is displayed in other views.

The Fortran projects view is similar to the Projects View.

Using the Fortran editor and Fortran perspective

Selecting free vs. fixed form; watermark indicating content type mismatch

Photran supports both fixed-form and free form Fortran code, each form having its own editor.

The free form Fortran editor allows the user to structure code as he/she wishes as long as it contains corrrect syntax.

The Fixed form Fortran reinforces the fixed-form Fortran syntax. If you are not familiar with the fixed form of Fortran programming, don't worry; Fixed form is more common in older Fortran programs, usually using Fortran-77 or earlier versions. Fixed form Fortran requires that all program statements are contained in columns 7 through 72. Anything after column 72 is ignored and anything before column 7 (except 'c', 'C', or '!' for comments) will result in a syntax error.

The Fixed form Fortran editor will notify you if your code is not correctly formatted. Opening free form code in the fixed-form editor will result in a watermark reading "Warning: Content Type Mismatch" being displayed in the upper right corner of the editor.

The free form editor is the default Fortran editor. If you wish to open fortran files in the fixed form editor, simply right-click the file in the project explorer > Open With > Fortran Editor (Fixed Form). To switch back to the free form editor, do the same, but select Fortran Editor (Free Form) instead.

Outline view - note Source Form marker in top, skull & crossbones

The Outline view in the Fortran perspective shows an outline of the structural elements of a structured file currently open in the editor. The Outline view notes what type of Fortran source (free form or fixed form) is open in the current editor. It will also note when there is an error in the code.

To add the Outline view to the current perspective go to Window > Show View > Other... > General > Outline.

Overview of the Fortran editors (incl. rulers, folding, smart highlighting)

Both the free form and fixed form editors support the same features. The main features to note are the horizontal ruler at the top of the editor, code folding, and smart syntactic highlighting.

The horizontal ruler indicates the width of the actual page you would be typing on. It shows dash and plus (-/+) characters for each column in the editor. It is possible to turn on the print margin in the 80th column. This is discussed further below in the section titled "Configuring the Editor."

Code folding is supported by the Fortran editors, but it is disabled and the horizontal ruler is enabled by default. Turning code folding on in the Fortran preferences will disable the horizontal ruler (how to do this is described below as well) and cause programs, functions, and subroutines to fold similar to how Java and C/C++ methods, classes, etc. fold.

The editors also support smart syntactic highlighting. As you write programs in Fortran, you will notice the different colors applied to Comments, Identifiers, Intrinsics, Keywords, and Strings to make code more readable. It is possible to change the colors for each of the previously mentioned code components in the Fortran editor preferences (this is discussed in the Configuring the Editor section).

Comment/uncomment

To comment a statement, type an exclamation point (!) before the desired comment. Removing the exclamation point will uncomment the statement.

Unfortunately, block comments are not supported in Fortran. Block comments may be supported in later releases of Photran.

Setting bookmarks

Eclipse supports Bookmarks which can be set on files or on specific lines of files to remember important locations within files. To set a bookmark, right-click the grey bar on the left side of the editor at the line where the bookmark should be located and select "Add Bookmark..." from the popup menu. A bookmark can also be placed on a line by locating the cursor on the line, going to Edit > Add Bookmark... in the menu bar. Type in the desired name for the bookmark in the dialog box and click OK. A blue bookmark will show up in the grey bar on the left side of the editor.

Bookmarks can also be viewed in the Bookmarks view (Window > Show View > Other..., select Bookmarks in the General folder).

Go to line (Ctrl+L)

To navigate to a specific line of code in the editor, there are two ways to access the "Go To Line..." feature. Open the file to navigate and

while the editor window is active, in the menu bar, go to Navigate > Go To Line... or press Ctrl+L to open the Go To Line dialog box. Typing in the line you wish to navigate to and clicking OK will locate the cursor at the beginning of the specified line and jump to that location.

Configuring The Editor

Selecting horizontal ruler vs. folding

The horizontal ruler at the top of the editor is enabled by default. To enable code folding and disable the horizontal ruler, go to Window > Preferences in the menu bar. Expand Fortran and select Editor. Check the appropriate box(es) to enable folding in the free-form and/or fixed form Fortran editor.

Setting Colors for syntax highlighting

The colors for Fortran syntax highlighting can be modified in the Fortran editor preferences. To modify the color settings, go to Window > Preferences in the menu bar. Expand Fortran and select Editor. The color choosers for Comments, Identifiers, Intrinsics, Keywords, and Strings are available on this page.

Showing Print Margin

To enable display of the print margin (column 80 in the editor) go to Window > Preferences in the menu bar. Under General, expand Editors, and select Text Editors. Check the box for "Show print margin". Click Apply and the print margin should now display in the editor.

Converting Tabs to spaces

To enable conversion of Tabs to spaces, go to Window > Preferences in the menu bar. Under General, expand Editors, and select Text Editors. Check the box for "Insert spaces for tabs" to have Eclipse automatically convert Tabs to spaces.

Show whitespace

Whitespace characters can be displayed by going to Window > Preferences. Under General > Editors > Text Editors, check the box next to "Show whitespace characters" and click Apply. Whitespace characters will now show up in the editor as grey dots.

Set Font

Changing font in the Fortran editor is currently not supported.

Show line numbers

Line numbers can be displayed in the editor in the Text Editor preferences page. Go to Window > Preferences. Under General > Editors > Text Editors, check the box "Show line numbers" and click Apply.

Compiling Fortran Programs

TODO

• refer to CDT

• Setting make targets - refer to CDT

• Error parsers

• Binary parsers - need to change if no "Run as Local Fortran App" menu item

Running and Debugging Fortran Programs

TODO

• refer to CDT

• Setting breakpoints

• Note compiler-specific problems

Advanced Features

Photran 5.0 includes a number of sophisticated features that are designed to make it easier to write, modify, search, and maintain Fortran code. These include content assist, which can "auto-complete" variable and function names as you type; a declaration view, which can show the leading comments for the selected variable or procedure; Fortran Search, which allows you to find declarations and references to modules, variables, procedures, etc.; and refactorings, which change your source code to improve its design while preserving its behavior.
Documentation for Photran's advanced features is available here.

Troubleshooting

If you are experiencing troubles with installing or working with Photran, you might want to check out our FAQ[7]

And if you don't find your answer there, feel free to e-mail them to our Mailing List[8]

Beyond Photran

TODO

• Using Photran with other Eclipse plug-ins

• • Subversion support

• • PTP/RDT

• • RSE