A Tutorial on installing and using Eclipse

SEG-N-0017 (2011) A Tutorial on installing and using Eclipse LS Chin, C Greenough, DJ Worth July 2011 Abstract This SEGNote is part of the material use at the CCPPNet Software Engineering Workshop. Its purpose is to give a short introduction to Eclipse and its use in a scientific software development project. We consider the installation of Eclipse, adding in new plugins and using Eclipse in a short test project. The test projects include the simple Hello World program and access cvs and svn repositories on CCPForge. Keywords: Tutorial notes, Eclipse IDE {shawn.chin, christopher.greenough, david.worth}@stfc.ac.uk Reports can be obtained from www.softeng.cse.clrc.ac.uk Software Engineering Group Computational Science & Engineering Department Rutherford Appleton Laboratory Harwell Science and Innovation Campus Didcot Oxfordshire OX11 0QX

c Science and Technology Facilites Council Enquires about the copyright, reproduction and requests for additional copies of this report should be address to: Library and Information Services STFC Rutherford Appleton Laboratory Harwell Science and Innovation Campus Didcot Oxfordshire OX11 0QX Tel: +44 (0)1235 445384 Fax: +44 (0)1235 446403 Email:library@rl.ac.uk STFC e-reports are available online at: http://epubs.cclrc.ac.uk Neither the Council nor the Laboratory accept any responsibility for loss or damage arising from the use of information contained in any of their reports or in any communication about their tests or investigations

Contents 1 Introdcution 1 2 Getting the necessary files 1 3 Development Software (Compilers/Builders etc) 1 4 Starting the ECLIPSE IDE 1 5 Using Perspectives in the Workbench 2 6 Creating and executing a simple project 2 7 Running a simple project in Debug Mode 3 8 Creating a project from cvs 4 9 Checking in changes 6 10 Creating a project from svn 6 11 Sorting out Proxy - If you have them! 7 12 Sorting Access to CCPForge with CVS, Subversion and Git 7 13 Sorting Compilation and Debugging 7 14 Photran - An Integrated Development Environment and Refactoring Tool for Fortran 8 15 Sorting Parallel Execution 8 16 Parallel Debugging 8 i

1 Introdcution These notes have been written with Windows and Linux in mind. Most things have been tried on these systems. Macs are a different kettle of fish - I don t have one. Most things should be the same - downloads and installation etc - but you can never tell! 2 Getting the necessary files Eclipse requires a good version of Java - Sun or IBM - 1.5 or more - www.java.com will give you a suitable version for Windows, Unix and Macs. jre-6u26-windows-i586-s.exe (Windows) jre-6u26-linux-i586.bin (Linux) I have only played with the Windows and Linux versions. Follow the instruction and they generally sort themselves out during installation. Check version with: beersheba% java -version java version "1.6.0_26" Java(TM) SE Runtime Environment (build 1.6.0_26-b03) Java HotSpot(TM) Server VM (build 20.1-b02, mixed mode) Eclipse - whatever distribution you like - Indigo - www.eclipse.org eclipse-parallel-indigo-incubation-win32.zip (Windows) eclipse-parallel-indigo-incubation-linux-gtk.tar.gz (Linux) I have used the Eclipse IDE for Parallel Application Developers. This an IDE for Parallel Application Developers. Includes the C/C++ IDE, plus tools for Fortran, UPC, MPI, a parallel debugger, etc. It includes PTP (http://www.eclipse.org/ptp/) - the parallel tools platform - which contains Photran 7.0 (http://eclipse.org/photran/). I have needed to add Subclipse and egit to provide svn and git access. We will do that later and some details can be found below. 3 Development Software (Compilers/Builders etc) Clearly to use eclipse we need to have the necessary tools installed on your machine. Any sensible Linux machine will have all the necessary things installed already apart from probably subversion and git. Windows machines are a mine field but I use Cygwin with a few additions and have used MinGW with success. Installing Cygwin (http://www.cygwin.com) takes much time but provides an acceptable Lunix environment. Installing MinGW (http://www.mingw.org) is much less difficult. From the downloads page download the latest version of the mingw installer (mingw-get-inst-20110530.exe) and execute. Most things get sorted apart from fixing the PATH environment variable to reference your MinGW binaries (usually C:\MINGW\BIN). When defining a project the compiler etc - the toolchain - will need specifying - MinGW GCC or Cygwin GCC on a Windows machine. Having both installed can cause problems! 4 Starting the ECLIPSE IDE This will depend on your system - but either a mouse click or command line, pointing to the correct location will start eclipse. It will start by asking you for a workspace to store your files and associated data. For the want of anything expect the default for now: 1

C:\<user id>/workspace - windows /home/<usr id>/workspace - linux OK should bring you to the Welcome scene - Welcome to the Eclipse IDE for Parallel Application Developers. Hover over the circles for information: Overview, What s new, First Steps, Samples, Tutorials and Workbench. Help from the menu will start the hep system. Help > Help Contents should start the help system in a new window or local browser. There is a bug in the linux distribution if proxies are involved. There are some comments on this later. 5 Using Perspectives in the Workbench Click Workbench on the welcome screen. Eclipse spends a lot of its time remembering where you were last time but the default perspective should be C/C++. What you see is a standard eclipse scene - a perspective - it is made up of views and editors. All should be blank at present. Window > Open Perspective > Other... will show you all the available perspectives in your installation. 6 Creating and executing a simple project We ll do the easy things first - creating a simple project. So start in the C/C++ perspective. Either do as above or click the C/C++ icon near to the top right of the eclipse window. Again most things will be blank. Now to create a simple project: File > New > Project (ignore the rest for the moment) brings up the New project wizard. Now work through the following steps: 1. Select a C Project from under the C/C++ (double click if necessary) part of the tree and click Next (at the bottom). You didn t know there were so many types of C Projects! 2. Let s go for Hello World ANSI C Project in the first executable list (third down - maybe) and we will need to select a Toolchain - could be Cygwin GCC, MinGW GCC or Linux GCC. We will need to give the project a name - hello will do. 3. Now click Next. Complete the Basic Settings if you fancy or click Next. 4. The project configuration can be long and complex so we will go with the defaults - a setup to construct Debug and Release versions. Finally click Finish. (You might be asked which perspective you want to associate with the project - depends on where you started from. You want the C/C++ perspective). 5. We are returned to the C/C++ perspective and our project has been created - hello - and the editor has open our source file. Clicking hello in the Project Explorer view reveals various directories etc associated with the project. Hovering the mouse over the highlighted icons produces some text on the functions in a standard sort of way. 2

6. To build the application - click the hammer! Something should happen - a few windows appearing and disappearing. The one to check is the Console view at the bottom of the page. This was taken from a Windows version running Cygwin. **** Build of configuration Debug for project hello **** make all Building file:../src/hello.c Invoking: Cygwin C Compiler gcc -O0 -g3 -Wall -c -fmessage-length=0 -MMD -MP -MF"src/hello.d" -MT"src/hello.d" -o "src/hello.o" "../src/hello.c" Finished building:../src/hello.c Building target: hello.exe Invoking: Cygwin C Linker gcc -o "hello.exe"./src/hello.o Finished building target: hello.exe **** Build Finished **** 7. All that remains is the execute the code. We first need to setup the run configuration. Run > Run Configurations We want a C/C++ Application - click - then add a configuration by clicking the new button - first one in the list of icons on top left. An empty page with a plus in the top right corner. This creates the hello Debug configuration. Click Close to exit. 8. Now clicking the green circle with white arrow will run the code. You may be promoted for which code to exectute. In our case it is a C/C++ Application. Again a few messages in the Console View. If you are quick you will notice the Run process also does a build just to ensure it has the most up to date version etc. The Hello World output is in the Console view. As you will have already seen there are many, many more options and perspectives within Eclipse. We will explore more of these later. 7 Running a simple project in Debug Mode 1. We will start by cleaning up the project. Either right click over the project name (hello) in the Project Explorer view or click: Project > Clean The first approach automatically cleans up and the second ask you what clean you want to do. The results is the same. 2. We build the project again. There are at least three routes to do this: click the hammer, right click the project name in the Project Explorer and then select Build Project or Project > Build Project By examining the Console view output you will notice that the code has been compiled and linked with the Debug options. See the output above. 3. To debug the code click the bug. You will be ask what perspective you require - clearly Debug. The perspective will change format to include a number of debugging views. 4. To run the code, click the yellow/green icon in the Debug view (top left). The code will run to completion as no break points hane been set. 3

5. To set a break point, right click in the source Editor (hello.c) at the very start of the line at which you want a break point and the Toggle Breakpoint can be click. A small green symbol will appear at the head of the line. 6. Run again (by clicking the bug) and the code stops at the first executable statement. 7. The other icons control stepping over and into code and the red box wil terminate the run. 8 Creating a project from cvs Now we will try getting information from CVS. 1. Switch perspectives to CVS Repositories: Window > Open Perspective > Other will list all the perspectives. Select CVS Repository Exploring. 2. We need to add a CVS Repository. Right click over CVS Repository view and then select Repository Location Now complete the form: Host: ccpforge.csel.rl.ac.uk Repository path: /cvsroot/felib User: anonymous Connection type: extssh 3. Clicking the entry will reveal the repository structure etc. Double click HEAD to show the module contents. 4. Right click over felib3 followed by Check Out As... 5. We are going to use the New Project Wizard so click Next. 6. Select HEAD and Finish. 7. In the wizard select Fortran Project and Next. 8. In Fortran Project scroll down and select Makefile project and Empty Project - Fortran. 9. The project name should be given and toolchain selected (if available - if not it gets sorted later) followed by Finish. 10. eclipse recognises the project type and suggests a perspective change - OK. 11. Now we have two projects in the Project view. 12. Clicking on the project name reveals the project files etc. 13. Build by clicking the hammer and watching the Console view. eclipse use the provided Makefile to build the application. This will only work if the toolchain has be selected. Go to Project > Properties 4

Now select Fortran Build and Tool Chain Editor. For Cygwin/minGW systems you need to un-check Display compatible toolchains only as you need to specify Cygwin GCC or mingw GCC. Apply and save (OK) to selections. Now hammer should work ok. Not that the contents of each build, run and debug is project dependent! What we would like to do is selectively compile and run one of the programs in this library of programs. We will select program seg3p1 as our example. 14. Clocking the program directory in the Fortran Project view show the programs and double clicking seg3p1.f will open it in an editor. 15. To make this code run under eclipse the input must come from a file. A small mod fixes this: 47 C SET ITEST FOR FULL CHECKING 48 C 49 ITEST = 0 50 OPEN(UNIT=NIN,FILE= data/dat3p1 ) 51 C The data is in the data directory. You must remember to save your changes - eclipse does not do this automatically. 16. Clicking hammer will re-build everything but really not necessary. 17. We create a new build configuration. Project > Properties Select Fortran Build and we see only one configuration. We go to Manage Configurations - top right - and click. In the resulting window we create a New configuration name - seg3p1 in this case. This can be based on any existing configuration but we only have Debug at present. OK takes us back to the manager and OK back to the project properties. 18. Make sure you have the correct configuration - seg3p1. We need to use a our own build command so uncheck Use default build command. In the box type make seg3p1 and change the working directory to $workspace loc:/felib3/programs We finally need to change the build Behaviour- click the tab and remove all from the incremental build configuration. Apply all things and OK the new project properties. 19. We can see our new build configurations: Project > Build Configurations > Manage We can highlight seg3p1 and make it the active configuration. 20. hammer will now build only the single program. 21. We finally want to execute this program under eclipse so we need a run configuration specific for this application. 5

22. Go to: Run > Run Configurations Click Fortran Local Application and then create a new configuration. Complete the form and apply. Select the executable from the project - in the programs directory - nothing else is required. 23. Back to the Fortran Perspective to run using the green circle with white arrow. The output should come to the Console view. 9 Checking in changes During this process we have change the source file seg3p1.f. You can see this by the little against it in the project view. You will see various other files marked in this way. 1. Right click over the file and select Team. This gives the interface commands to the repository - Update, Commiti etc. These act in the way might hope (but don t commit anything!). 2. Select Compare with > Latest from HEAD and you will get a comparison editor. 10 Creating a project from svn Some may have subversion repositories. Once you have sorted a subversion client for eclipse much is the same as CVS. I have installed subclipse. 1. So a change of perspective to define an svn source: Window > Open Perspective > Other.. Now select SVN Repository Exploring. 2. Right click in the SVN Repositoies view and select New Repository Location. 3. Complete the form with the repository URL: http://ccpforge.cse.rl.ac.uk/svn/xagents At this point you may need a username and password - use: username: wksh1 password wksh1$wksh1 A click on the entry will fetch the repository information. We are going to take the xparser directory from trunk. 4. Right click over xparser and select checkout. We will use the Wizard so just click Finish. 5. Select a C Project and then Next. 6. Now select an Empty Project from the Makefile project list and a suitable toolchain. Give the project a name and click Finish. 7. eclipse will want to change perspective for you - fine. You might get some other comments - click OK. We now have a new project xparser taken from an svn repository. 8. Clicking hammer will build the project using the default build. Monitor progress in the Console view. 6

11 Sorting out Proxy - If you have them! Proxies are a pain. All the user options are found under: Window > Preferences This will open a new window and a list as long as your arm. To ensure all things you ok we with set the proxy and make help use an external browser. So in this new window: General > Network Connections By setting Active Provider to Manual all the proxy setting can be added using Edit. By using General > Help we can set the Help browser to external. At this point it is a good idea the restart eclipse. 12 Sorting Access to CCPForge with CVS, Subversion and Git CVS: Not a problem really. The necessary CVS interfaces are installed by default in the CVS Repository Exploring perspective. For CVS you just need to get the protocols correct when defining the repository - use extssh and all should be well. SVN: Subvision requires adding a plugin - Subclipse appears to the easiest. Best fetch by using the Eclipse Marketplace. Help > Eclipse Marketplace Search for subversion and you will have a number if choices. I have gone for Subclipse. Click install and the rest is history apart from signing the usage agreement etc and agreeing to installing the files. For Windows all goes through with no problems and you will need to restart eclipse. On Linux systems it will depend on what libraries you have installed. You need to install the necessary JavaHL because eclipse use the API to talk to the svn server.this is a mess as you need to install JavaHL and then tell eclipse where to find it. You can find details here: http://subclipse.tigris.org/wiki/javahl You are only really after the libraries for eclipse to use and not having the server running. The install will fail if you install as root but that is not a problem. Once installed details need adding to eclipse. In the eclipse.ini file put the following -vmargs -Djava.library.path=/opt/csvn/lib where the path name is where you have put the libraries - /opt/csvn/lib in my case. Where this should go in the eclipse.ini is not well defined but I put it just after the first reference to eclipse. 13 Sorting Compilation and Debugging This is ok you just have to sure that the necessary configurations are setup: Project > Properties and then look at C/C++ Build for configurations. Manage Configuration allows you to add new configurations and rename current ones. 7

14 Photran - An Integrated Development Environment and Refactoring Tool for Fortran Photran is an IDE and re-factoring tool for Fortran based on Eclipse and the CDT. Photran 7.0 was released with Eclipse 3.7 (Indigo) on June 22, 2011. Photran 7.0 supports Fortran 77-2008. It includes 31 re-factorings (including Rename, Extract Procedure, and loop transformations), as well as the following IDE features: Syntax-highlighting editor Outline view Content assist* Open declaration* Declaration view and hover tips* Fortran language-based searching* Support for CVS & other VCS s** Interactive debugger (gdb GUI) Makefile-based compilation Optional Makefile generation Recognition of error messages from most popular Fortran compilers 15 Sorting Parallel Execution PTP will manage parallel execution of a code and it is possible to debug in parallel. The step are straightforward if you follow the PTP documentation. The only difficulty is ensuring that the necessary MPI system information is available. 16 Parallel Debugging There is only interface for parallel debugging. This will need buidling once PTP is installed. The build require executing sh BUILD in the appropriate directory: eclipse/plugins/org.eclipse.ptp.linux.x86 5.0.0.201106140904 where only the first part is important ptp.linux.x86... Executing the build will generate the necessary sdm program in the bin directory. 8