Photran Tutorial [reprint]

this article comes from "http://www.fesb.hr/~psarajce/photran.html"

 

----------------------------------------------------------------

 

Photran Tutorial  

 

Photran is a full featured Fortran IDE for Linux OS (IDE - Integrated Development Environment). It can be bundled with various Fortran compilers (e.g. Intel Fortran Compiler, F compiler, G95, gfortran, etc.), which means that it is not dependent upon any particular Fortran compiler. It is completely GUI interfaced, with included front-end for underlaying fortran debugger. Project development is maintained through the use of standard "make" utility and a user written makefiles. This means that user writes its own makefile and uses underlying Fortran compiler present on his system to build and execute programs, directly from the Photran IDE. Latest version of the Photran IDE at the time of writing this is 4.0, which includes a Managed Make Fortran Projects, which means that Photran automatically creates makefiles for new Fortran projects. By using the version 4.0 of Photran IDE user doesn't need to write his own makefile (Photran automatically creates one for his project), as will be explained later. This is only the case with Intel Fortran Compiler and Gnu Fortran compiler. This Fortran IDE is based on Eclipse and hence highly adaptable. Its editor has a syntax highlighting for Fortran 90/95 programming language (including the brackets matching feature). It has also syntax highlighting support for the built in makefile editor, which simplifies the process of writing makefiles, without leaving this application. It can be said that Photran IDE supports FORTRAN 77 syntax as well and thus can be used to develop these type of Fortran projects. Due to the fact that Fortran 90/95 routines could flawlessly call routines written in FORTRAN 77, legacy code could be easily exploited through "mixed language" (F90/95 + F77) source code projects, developed within this Fortran environment. This environment is called the Workbench . The term Workbench refers to the desktop development environment. The Workbench aims to achieve seamless tool integration and controlled openness by providing a common paradigm for the creation, management, and navigation of workspace resources. Each Workbench window contains one or more perspectives.  Perspectives contain views and editors and control what appears in certain menus and tool bars.  More than one Workbench window can exist on the desktop at any given time.

Photran application (Workbench) can be extensively configured by positioning its window parts in a manner desired by the user itself. Example of the window positions / configurations is given in the figure above. On the left side of that figure the files included in the project are alphabetically listed. Central area in the mentioned figure features a pane / window where the source files are displayed for editing. Photran editor supports tabs for editing several source code files simultaneously. It is in fact a full-featured Fortran programming language editor with syntax highlighting (as can be seen from the above figure). It fully supports Fortran 90/95 programming language! Multiple source code files could be opened in the editor, which are shown in the form of tabs above the editors window. User jumps from one source code file to the other just by clicking on the desired tab. Active tab is shown in blue. Bottom part of the figure shows a build window where the compiler information is displayed during the build process. All compiler warnings and errors are shown in this window, including the line number in the source code where the error is detected. By clicking on the error line in this window a cursor is positioned on the source code line in editor window where the error is found. This greatly simplifies the process of hunting down compilation errors. Several other windows could be opened and positioned according to the users needs. One possible configuration is presented in the above figure.

Photran software package has different workspace perspectives; one for the Fortran project development (writing source code and building application) which is opened by default, and the other for debugging the fortran project / application. Workspace persppective for developing fortran application is shown in the above figure, which is signified with the active Fortran tab on the upper right corner of the application / workbench window. Photran supports debuggers for the Fortran programming language, which are bundled with this IDE. Hence, one can debug his Fortran projects directly from the Photran IDE! Debugging process initiates a new workspace perspective designed for debugging a Fortran projects / programs. This perspective can be extensively configured as well. 

When using Photran, your code is organized into workspaces and projects. A project usually will contain the code for one complete program, consisting of a main program, several subprograms and possibly some modules organized in several source code files. These files, and others used by the Photran system, usually are stored in one directory whose name is the name of the project. A workspace consists of projects; it uses a directory whose name is the name of the workspace to store the project directories. A workspace might contain only one project or several of them. Only single project can be active at any given time. You can freely open and close projects within the workspace, but only the currently active project can be modified. In order to use Photran for Fortran 90/95 development, you must create a project, which is part of some workspace. You then add source code files to that project, either by copying existing files into the project or by creating new source code files and typing in the code. Then, using the Photran, the project can be built, run, and debugged.

As a conclusion of the introduction to the main Photran features it can be stated that extensive documentation regarding Eclipse platform can be obtained within this application (Help => Workbench user guide ). All of this documentation regarding the Eclipse workspace (Workbench) organization and usage is directly applicable to the Photran environment.

User is advised to get familiar with this documentation which is bundled directly into the Help system of the Photran software package. Above figure presents this Help system with documentation regarding The Workbench. Here user can find extensive description of all concepts and get detailed step-by-step instructions on creating and managing projects and files. As a part of this official Photran Help system there is a C/C++ Development User Guide (which can be seen on the above figure). This guide can be applied (with minor modifications on the lines described in this document) to Fortran 90/95 development.

Installation procedure

 

Installation process for the Photran IDE application on Linux platform is very easy. One only needs to download the application from eclipse project web pages. Best is to use the Full versions, such as: Full Photran for Linux/GTK (32 bit architectures) or Full Photran for Linux/GTK x86/64 (64 bit architectures). It is a "tar ball" which needs to be extracted somewhere. By extracting this tar ball a new directory is created named: eclipse and the process of installation of Photran is finished! Application is executed by running the program: eclipse in the same directory. You can make a symbolic link to the executable file: eclipse to make it more convenient to launch the application.

If you already have eclipse or eclipse and CDT installed on your system you can for example create a new directory called: Photran and extract this tar ball here, in order not to collide with the existing directory called: eclipse (which contains your standard eclipse application).

 

In newer versions of Photran, installation procedure is somewhat different from tha described above. To install Photran 4.0 beta 5,

1. you must have Eclipse 3.4 (Ganymede) installed,
2. you must have the C/C++ Development Tools (CDT) 5.0 installed,
3. Eclipse must be running on a Java 1.5 or later JVM (to get reasonable performance, we recommend Sun [1] or IBM's [2] JVM), and
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 are below.

 

Firstly you need to download and install Eclipse version 3.4. Installation instructions for Eclipse could be found on their web site. It is a very straightforward task, which basically involves an extraction of a tar ball somewhere in your home directory. You end up with an eclipse directory which containes project directories and executable (called eclipse). You might want to put a simbolic link to this executable in order to be able to access it more rapidly. Once that has been taken care of you can proceed with the installation of Photran plugin. To install Photran, start Eclipse 3.4, 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) (Eclipse Technology Incubation)"
10. If you have Intel Fortran installed on Linux then expand "Photran Compiler Support" and select the appropriate compiler as well.
11. Click on the "Install..." button in the upper-right corner of the dialog box.

Installation has been tested by the author of this file on openSUSE Linux distribution (several versions of openSUSE, e.g. 10.0, 10.2, 10.3 and with different versions of Linux kernel) and can be reported to work without any problems. Photran, once installed, just "picks up" any Fortran 90/95 compiler which is present on the system, through the provided makefile. It has been tested by the author with the Intel Fortran Compiler for Linux (several versions, e.g. 8.1, 9.0, 9.1) and can be reported to work flawlessly. It has been also tested with the gfortran (which is a part of the GCC) and G95 Fortran compiler and works without any problems.

Building projects

This part of the Tutorial is intended for the 3.2.0 version of the Photran IDE. Tutorial for the Photran 4.0 version is given later in the text. Process of building a new Fortran 90/95 project in Photran IDE is very similar to the project building process in any other Development Environment (including those on Windows OS, e.g. Compaq Visual Fortran Development Environment). One starts with the: File => New => Project... which opens a dialogue box presented in the following figure.
 


In this dialogue, under the Fortran category one must select: Standard Make Fortran Project and press on the Next> button. A new dialogue box, presented in the following figure, opens. It needs to be said that at this stage of Photran IDE development Managed Make Fortran Projects are NOT supported  (in the version 3.2.0 of the Photran IDE)!



Here one needs to define the name of the project (e.g. HelloWorld is the name selected for the project considered in this tutorial) and the directory to hold this project. Projects could be saved / accumulated in the default workspace directory of the eclipse application. This is recommended practice. Press on the Next> button and then on the dialogue box which opens select the Make Builder tab , as shown in the following figure.



Here, specify Build command (make), Incremental build (all) and Clean (clean) as shown in the above figure. This will be used in combination with the makefile to build the project (or incrementally build it, or clean the project for the so-called clean build). Other tabs shown in the above figure are not crucial (significant) for the creation of the project and can be left with default values. Once the project is created these values can be changed by choosing: Project => Properties and selecting the category: C/C++ Make Projects  (in the version 3.2.0 of the Photran IDE). Press on the Finish button and you have just created a new Fortran project, which is completely empty. Hence, you need to add some source code fi
les and finally a makefile.

If you already have Fortran 90/95 source files somewhere on the system you can import them into this newly created project. This can be accomplished by selecting the: File -> Import... which opens the import dialogue box (same thing could be accomplished by right clicking on the Project icon in the left side pane and selecting the Import ... command from the drop down menu. Otherwise you need to create new Fortran 90/95 source code files.

To add new Fortran source code files into this project select: File => New => Source File which opens the dialogue box presented in the following figure.



Enter the name of the source code file, including the file extension .f90 and the press the Finish button. This source code file is automatically opened in the Fortran editor ready to be edited. This process can be repeated for any number of source code files which will comprise the final project.

In order to build this project one needs to create a makefile . In order to create a new makefile select: File => New => File which opens the following dialogue box, presented in the figure below.



In the file name field enter: makefile and press Finish button. A new makefile is opened in the editor window of the Photran IDE  application ready to be edited / created.

If you already have a makefile created for this project (or some other makefile which you will edit for this project) somewhere on the system, you can import it into this newly created project. This can be accomplished by selecting the: File => Import... which opens the import dialogue box (same thing could be accomplished by right clicking on the Project icon in the left side pane and selecting the Import ... command from the drop down menu.

Makefile must be created in the distinct way (as will be explained later in this section) in order to be compatible with the commands selected on the Make Builder dialogue box during the process of creating the Fortran project. This is in regard with the use of all and clean parts of the makefile. Strict rules need to be followed, as explained below, otherwise project might not compile or link properly.

Let us say for example that one has only one source code file called: hello.f90 containing all the source code for the project. In that case the makefile could be something like this:

# This makefile uses Intel Fortran Compiler for Linux # Start of the makefile all: hello hello: hello.o     ifort -o hello hello.o hello.o: hello.f90     ifort -c hello.f90 # Cleaning the project clean:     rm hello.o hello # End of the makefile

In the makefile above a name hello is selected for the executable file. More advanced makefiles which include variables and other advanced features could be crated as well. It should be noted that the rule all must be the first rule in the makefile, with Make Builder configured as explained earlier.

Once the source code file(s) is(are) edited / created and a particular makefile is created for the project in question, one can proceed with the actual building of the project. Building procedure consists of the compile and link stages, which are defined through the makefile. In order to build the project choose: Project => Build All . Any compiler errors and warnings will be displayed in the Problems
pane of the Photran application window. This pane is usualy positioned at the bottom of the Photran IDE window and can be activated by selecting its tab. By selecting the line with the displayed compiler warning in the Problems pane the cursor is automatically positioned in the source code line in editor window where that error is found. This greatly simplifies the process of hunting down bugs in the compilation phase of the Fortran project development.

Running the successfully built (compiled and linked) application is accomplished by selecting: Run => Run As => Run Local C/C++ Application which executes that Fortran application. Yes it says Run Local C/C++ Application by you are running the Fortran Application (in the version 3.2.0 of the Photran IDE)! It should automatically open the console window and display any Fortran application text that is sent to default output stream. If the console window is not opened click on the console window icon (whose position depends on the organization of the Photran workspace) and console window will open. Console window is usualy positioned at the bottom portion of the Photran IDE window and can be activated by clicking on its tab.

Interaction of the user with the Fortran program can be accomplished through the console window and / or data files, which could be created and maintained directly within Photran workspace. To add new data file (with any extension which is supported by Fortran language) for the input data, select: File => New => File and in the opened dialogue enter the file name with the extension (e.g. input.dat). A new file will automatically open in the editor window, where you can input the necessary data. Output files could be browsed from the Photran workspace as well. Just choose Navigator pane and double click on the file that holds output data. It will display in the editor.

Several Fortran projects could be managed at the same time in the Photran workspace. Once you have temporarily finished working with one project close it and open the other one for editing (or create a new project). Only a single active project can be edited and / or executed at any given time.

Photran version 4.0

This version of Photran uses CDT 4.0.1 and Eclipse 3.3.1 and have some additional useful features which weren't present  with previous versions (e.g. version 3.2.0 of the Photran IDE). This version (Photran 4.0.1) includes the Managed Make Fortran Projects for the Intel Fortran Compiler for Linux and GNU Fortran compiler. This means that the Photran IDE is automatically creating makefile for the user. Hence, one only needs to create or import source code files and Photran takes care of the makefile. This is a useful feature for those Fortran programmers  / developers which are not used to writing their own makefiles. For those Fortran programmers  / developers which are used to writing their own makefiles, this version can be used in the manner described above. Photran software package, due to the fact that it is a part of the Eclipse project, is under constant development and improvement. Hence, each new version is more user friendly with additional built-in functionality. It needs to be said that Photran 4.0 has more than enough functionality even for the advanced user (software developer) and could be considered as fully functional Fortran 90/95 IDE for Linux OS. Every newer version will bring additional functionality and hence could certainly satisfy Fortran developers.

For example, if one would want to create a Managed Make Fortran Project with Photran 4.0 IDE and have an Intel Fortran Compiler for Linux (link ) installed on the system, it can proceed as follows: File => New => Project... which open the followng dialogue box shown in the figure below. From that dialogue select the Fortran Project under the Fortran category as shown in the figure below.



Press the Next> button, which will open the following dialogue box, preseneted in the figure below.



Under the Project types on the opened dialogue box select the Executable (Intel(R) Fortran) , as shown in the figure above. Under the Project name enter the name of the Fortran project (e.g. HelloWorld is selected for the Fortran project used in this example). Press the Finish button and a new Fortran project is created. Now all one needs is to add new (or import) source code file(s) and build the project. Makefile for the project is automatically created by the Photran IDE! Building the Fortran project is the same as has been previously described. It needs to be said that Intel Fortran Compiler for Linux is available free of charge for non-commercial development. This is a great, extremely fast compiler, especially tuned for Intel processors (dual and quad core, 32 and 64 bit). This compiler supports OpenMP as well as automatic vectorization and parallel optimization of the source code (through various compiler options).

If you want to use the "standard" procedure with user created makefile, from the above presented dialogue box, under the Project types: append the Executable category and select the Empty project ! Now you need to create or import source code files and a makefile for the Fortran project.

Running the successfully built (compiled and linked) application is accomplished by selecting: Run => Run As => Run Local C/C++ Application which executes that Fortran application. It should automatically open the console window and display any Fortran application text that is sent to default output stream.

Managing data files is accomplished in the exactly the same way as previously described. Several Fortran projects could be managed at the same time in the Photran workspace. Once you have temporarily finished working with one project close it and open the other one for editing (or create a new project). Only a single active project can be edited and / or executed at any given time.

Final notes

I would definitely recommend an upgrade to the newest version of the Photran, which is at the time of this writing Photran 4.0 with CDT 4.0.1 and Eclipse 3.3.1. This Fortran IDE, through the Managed Make Fortran Projects feature, simplifies the procedure of building Fortran projects. For those Fortran programmers / developers which are used to building their own makefiles, everything is the same as has been with the older versions. Though, user interface for defining Fortran project features is more user friendly in this version. Photran 4.0 IDE has been tested with openSUSE 10.3 (KDE) and Intel Fotran Compiler 10.1. It works without any problems, including Managed Make Fortran Projects feature. Debugging Fortran projects is also tested and works just fine. Finally, Photran software package, due to the fact that it is a part of the Eclipse project, is under constant development and improvement. Hence, each new version is more user friendly with additional built-in functionality. As a final note it needs to be said that Photran 4.0 has more than enough functionality even for the advanced user (software developer) and could be considered as fully functional Fortran 90/95 IDE for Linux OS.