Revision as of 17:23, 16 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...

1. You must have Eclipse 3.5 (Galileo) installed.
2. 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.
3. 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.
4. 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)

1. Click Next
2. Click on Advanced Settings
3. Expand C/C++ Build in the list on the left, and click on Settings
4. 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.

1. Click on the Error Parsers tab. Check the error parser(s) for the

Fortran compiler(s) you will use.

1. Click OK
2. Click Finish
3. Click File | New | Source File
4. Call it hello.f90; click Finish
5. 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 

1. In the Fortran Projects view, expand the Binaries

entry, and click on your
executable (e.g., "whatever - [x86le]") 

1. Run | Run As | Run Local C/C++ Application (yeah, I

know, it should say "Fortran Application", but it doesn't) 

1. Choose GDB Debugger (Cygwin GDB Debugger if you're

under Windows) 

1. 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

1. Call it whatever

1. Expand "Makefile project" in the project type list (it has a folder icon),

and choose Empty Project

1. Make sure "-- Other Toolchain --" is selected in the

toolchain list in the right-hand column, and
click Next

1. Click on Advanced Settings

1. Expand C/C++ Build in the list on the left, and click on Settings

1. 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.

1. Click on the Error Parsers tab. Check the error parser(s) for the

Fortran compiler(s) you will use.

1. Click OK

1. Click Finish

1. File | New | File

1. Call it Makefile

1. Click Finish

1. 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

1. Call it hello.f90

1. Click Finish

1. Type the standard "Hello, World" program.

program hello
    print *, "Hello World"
end program

1. Project | Clean; then click OK

1. Open the Console view, and make sure "make" ran OK

and compiled your program 

1. In the Fortran Projects view, expand the Binaries

entry, and click on your
executable (e.g., "whatever - [x86le]") 

1. Run | Run As | Run Local C/C++ Application (yeah, I

know, it should say "Fortran Application", but it doesn't) 

1. Choose GDB Debugger (Cygwin GDB Debugger if you're

under Windows) 

1. Check the Console view, and make sure Hello World appeared.

Writing Code

TODO

• The Fortran Perspective

• The Fortran Projects View

• Using the Fortran editor and Fortran perspective

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

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

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

• • Comment/uncomment

• • Setting bookmarks

• • Go to line (Ctrl+L)

• • Configuring the editor

• • • Selecting horizontal ruler vs. folding

• • • Setting colors for syntax highlighting

• • • Showing print margin

• • • Spaces instead of tabs

• • • Show whitespace

• • • Set font

• • • Show line numbers

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