Skip to main content
Jump to: navigation, search

Difference between revisions of "PTP/photran/documentation/photran5"

m (Advanced Features)
(Troubleshooting)
Line 256: Line 256:
  
 
=Troubleshooting=
 
=Troubleshooting=
TODO
+
If you are experiencing troubles with installing or working with Photran, you might want to check out our FAQ[http://wiki.eclipse.org/PTP/photran/faq]<br>
* FAQ
+
And if you don't find your answer there, feel free to e-mail them to our Mailing List[http://eclipse.org/photran/mailinglists.php]
* Mailing list
+
  
 
=Beyond Photran=
 
=Beyond Photran=

Revision as of 10:45, 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).

Instructions for MinGW: Just a quick warning, installing MinGW by hand is a bit hacky and tedious, so keep that in mind when you read through the process

  1. Go to the MinGW download site[7] and download the following packages:
    1. GNU Binutils
      1. binutils-2.19.1-mingw32-bin.tar.gz[8]
    2. GCC Version 4
      1. gcc-core-4.4.0-mingw32-bin.tar.gz [9]
      2. gcc-core-4.4.0-mingw32-dll.tar.gz[10]
      3. gmp-4.2.4-mingw32-dll.tar.gz[11]
      4. mpfr-2.4.1-mingw32-dll.tar.gz[12]
      5. gcc-fortran-4.4.0-mingw32-bin.tar.gz[13]
      6. gcc-fortran-4.4.0-mingw32-dll.tar.gz[14]
      7. Optional gcc-c++-4.4.0-mingw32-bin.tar.gz[15]
      8. Optional gcc-c++-4.4.0-mingw32-dll.tar.gz[16]
    3. MinGW Runtime
      1. mingwrt-3.15.2-mingw32-dll.tar.gz[17]
    4. MinGW API for MS-Windows
      1. w32api-3.13-mingw32-dev.tar.gz[18]
    5. GNU Make
      1. mingw32-make-3.81-20080326-3.tar.gz[19]
    6. GNU Source-Level Debugger
      1. gdb-6.8-mingw-3.tar.bz2[20]
  2. If you need help un-packing the archives, here are tools that will help as recomended on official MinGW website:
    1. Gzip for Windows[21]
    2. LibArchive for Windows, TAR[22]
  3. Create a new folder C:\MinGW and unpack all files into it. Don't worry about overwriting files if you have to. Warning Do not change the install directory of MinGW unless you know what you are doing.
  4. Now we need to change the environment variable PATH to include the MinGW directory. The following manual is taken directly from MinGW's "HOWTO Install the MinGW GCC Compiler Suite"[23] Warning: Adding entries to the PATH is normally benign. However, if you delete, you may mess up your PATH string, and you could seriously compromise the functioning of your computer. Please be careful.
    1. Right-click on "My Computer" and select "Properties".
    2. Click Advanced -> Environment Variables.
    3. In the box entitled "System Variables" scroll down to the line that says "PATH" and double-click the entry. You will be presented with a dialog box with two text boxes, the bottom text box allows you to edit the PATH variable. It is very important that you do not delete the existing values in the PATH string, this will cause all sorts of problems for you!
    4. Scroll to the end of the string and at the end add ";<installation-directory>\bin". Here <installation-directory> is the full absolute path name of the installation directory; if you accepted the defaults when installing tar and gzip, then for these, it will (probably) be C:\Program Files\GnuWin32, while for MinGW it will be C:\MinGW\bin, (if you kept to the recommended default installation directory). Don't forget the semicolon; this separates the entries in the PATH.
    5. press OK -> OK -> OK and you are done.
  5. Finally, go to the <MinGW_install_directory>\bin and re-name mingw32-make.exe to make.exe
  6. You are done!

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
  15. Open the Console view, and make sure "make" ran OK and compiled your program
  16. In the Fortran Projects view, expand the Binaries entry, and click on your executable (e.g., "whatever - [x86le]")
  17. Run | Run As | Run Local C/C++ Application (yeah, I know, it should say "Fortran Application", but it doesn't)
  18. Choose GDB Debugger (Cygwin GDB Debugger if you're under Windows)
  19. 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</li-->
  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:
    
    
  15. File | New | Source File
  16. Call it hello.f90
  17. Click Finish
  18. Type the standard "Hello, World" program.
    program hello
        print *, "Hello World"
    end program
  19. Project | Clean; then click OK
  20. Open the Console view, and make sure "make" ran OK and compiled your program
  21. In the Fortran Projects view, expand the Binaries entry, and click on your executable (e.g., "whatever - [x86le]")
  22. Run | Run As | Run Local C/C++ Application (yeah, I know, it should say "Fortran Application", but it doesn't)
  23. Choose GDB Debugger (Cygwin GDB Debugger if you're under Windows)
  24. 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[24]
And if you don't find your answer there, feel free to e-mail them to our Mailing List[25]

Beyond Photran

TODO

  • Using Photran with other Eclipse plug-ins
    • Subversion support
    • PTP/RDT
    • RSE

Back to the top