Using Eclipse CDT for developing OpenFOAM
Please note: This offering is not approved or endorsed by OpenCFD® Limited, the producer of OpenFOAM® software and owner of the OpenFOAM® and OpenCFD® trademarks.
Contents
- 1 Thanks to ..
- 2 Versions
- 3 Eclipse Capabilities
- 4 Aim of the tutorial
- 5 Download and set up Eclipse
- 6 Developing and compiling
- 7 Running applications and debugging
- 8 Profiling with gProf and Linux Tools
- 9 Annotations and hints
- 10 Groups on extend-project
- 11 Training Session from 6th OpenFOAM Workshop: Integrated Environment Development (IDE) Eclipse for OpenFOAM
1 Thanks to ..
Patrik Eder for his help with setting up Eclipse and Holger Marschall for proofreading.
2 Versions
Operating system: openSuse 10.2
OpenFOAM version: OpenFOAM-1.6.x
Eclipse version: eclipse 3.5.1 (eclipse Galileo)
GNU Debugger (gdb) version: 6.8
Please be careful choosing the right gdb version! In gdb 7.x a bug seems to occur while debugging and monitoring the variables.
3 Eclipse Capabilities
"Eclipse is an open source community whose projects are focused on building an extensible development platform, runtimes and application frameworks for building, deploying and managing software across the entire software lifecycle. Many people know us, and hopefully love us, as a Java IDE but Eclipse is much more than a Java IDE." - www.eclipse.org
Eclipse is a powerful integrated development environment IDE originally developed for Java programming. But with the C/C++ Development Toolkit (CDT) extension Eclipse becomes a very common IDE for C++ programming.
If you want to work on a project in OpenFOAM, it is even not necessary to import the whole OpenFOAM-folder. Only import the project you are working on and the rest of the code will be linked for developing and debugging.
4 Aim of the tutorial
In this tutorial we will import a standard OpenFOAM solver and set up Eclipse for OpenFOAM. After a short introduction in Eclipse's developing features for applications and libraries, debugging in the Eclipse environment using the GNU Debugger GDB will be presented. Everything will be carried out with simpleFoam on the test case pitzDaily while having a look at the turbulence models as libraries.
5 Download and set up Eclipse
To start developing OpenFOAM with Eclipse just download the current version for C/C++ from www.eclipse.org/downloads/. This version already contains the C++ extension CDT (C/C++ Development Tools). Unpack the downloaded file and start Eclipse by clicking on the executable or start Eclipse from the terminal after setting the path variable.
For more information on CDT and CDT installation refer to Further information.
5.1 Install CDT by hand
If you have installed eclipse with your proper package manager, you'll might need to install CDT by hand, if it is not available as package. To do this, go to: Help -> Install New Software... ; Add ... a new site with the location of the CDT plugin http://download.eclipse.org/tools/cdt/releases/galileo/ You might have to adapt the name of the eclipse release. After fetching the site.xml, select the appropriate plugins. Click Finish.
5.2 Launching C++ project
While launching create your own workspace or use the default workspace (for further information refer to Limit the number of sources). Change developing environment to C++ in the menu bar under Window -> Show View -> C/C++ Projects. Create a new C++ project in the menu bar under Files -> New -> C++ Project. A C++ project can be a test case, an application or a library of OpenFOAM. Deactivate Use default location, then select the folder you want to import. Set a name for your project. Click Finish.
Now, set the OpenFOAM compiler properties for Eclipse. Right-click on your new project in the project explorer on the left side, select properties. Set the compiler command under C/C++-Build. Deactivate the default build command and type in OpenFOAM's wmake. Deactivate Generate Makefiles automatically. Set the build directory – maybe you have to remove the /Release or /Debug. Click OK. Make sure, that Project -> Automatically build in the menu bar is deactivated.
Full code completion can be achieved using the correct lnInclude paths as shown below. For this click right on project Properties->C/C++->PathsandSymbols and include the needed lnInclude paths for GNU C++ compiler.
6 Developing and compiling
Open your project folder in the project explorer and double-click a file, so the editor will open the file in the middle of your screen. You can now edit your file comfortably with the Eclipse text editor. Code highlighting for C++ is default setting.
The Eclipse editor offers some advantageous tool as the indexer that searches your workspace or project for variables and objects. Another tool is the automatic completion for functions. Call a class and set a „dot“ for a function after it, and you will be offered a list of available functions including parameters. This allows fast programming and avoids searching and jumping between windows. Errors and warnings are marked on the left side of the editor window. Additionally you can set bookmarks or tasks. But please keep in mind that the indexer works only for the imported parts of OpenFOAM (see also this tutorial on how to get the indexer to work).
On the right hand side you can select the outline tab, which presents you the outline of current functions, namespaces and files. (Hint: If the outline tab is missing select: Window -> Show View -> outline – this is valid for all views)
If you want to compile a certain part of your imported project, you must create a make target for Eclipse. Therefore select the make targets tab on the right side of the window. Select the folder where your Make folder is in, and create a new make target with the new make target button.
For compiling an application create a make target named wmake and leave the make target box plain. Build command is the default wmake -- corresponding to the console command wmake.
If you want to execute wclean, create a make target named wclean and leave the make target box plain again. Change the build command to wclean.
Execute your make target by double-clicking on it and watch the output in the console window.
Now, create your own turbulence model as described in the OpenFOAM Wiki tutorial "How to use your own turbulence model" of the Special Interest Group (SIG) Turbomachinery. Import the library as C++ project as mentioned above. For compiling the new turbulence model using wmake libso in OpenFOAM, name your make target libso – the build command stays wmake. In analogous way create a wclean libso make target.
6.1 Error "Cannot run program "wmake" "
In case that Eclipse shows the error Cannot run program "wmake" either start Eclipse from a terminal that can run OpenFOAM commands or run wmake/wclean or any other OpenFOAM command as an argument to the foamExec script by replacing wmake or any other OpenFOAM command with /opt/openfoam210/bin/foamExec foamCommand. Now Eclipse knows where to look for the OpenFOAM command and Eclipse can be started without having to open an extra terminal.
Also, see the post by Bruno Santos to this in the forums: Eclipse for OpenFOAM.
6.2 Eclipse shows a lot of errors, which are no errors
OpenFOAM #include-s many headers in a way which the Eclipse indexer does not understand. Since Eclipse does not understand those files, it will not recognize things (e.g. variables) declared within them. This is the cause for the "errors" you are witnessing. Luckily, it is possible to get around this by "fooling the indexer". This method will enable the Eclipse indexer to recognize all symbols, and thereby "Open Declaration (F3)" and autocompletion will work.
7 Running applications and debugging
For testing a solver begin with importing the test case folder as a C++ project as mentioned before – you should run your preprocessing tools as blockMesh in the terminal on beforehand. Then set up the run configurations in the menu bar under Run -> Run Configurations. Choose your test case as project and your solver as application. Here, the test case pitzDaily is chosen as project and the solver simpleFoam is chosen as application. To start your simulation just click on the run button and follow the console output.
It is also possible to debug applications under Eclipse with the GNU Debugger gdb. Therefore you may need to compile your OpenFOAM version in the debug mode of the compiler. Change the compiler settings in OpenFOAM/OpenFOAM-1.6.x/etc/bashrc to debug with WM_COMPILE_OPTION:=Debug and compile OpenFOAM using ./Allwmake. This will take a few minutes.
Open the configurations for debugging under Run -> Debug Configurations. Choose the same settings for project and application as for the run configurations. Finally make sure, that you are using the GDB (DSF) Create Process Launcher. If necessary, change it by clicking on hyperlink Select other.
Start debugging by clicking on Debug. Now, the debug perspective should open – if not, activate it in the menu bar under Window -> Open Perspective -> Debug. The program should stop at the first breakpoint that is default set to the begin of main{}. Now you can set breakpoints by clicking on the bar left in the editor window. Restart debugging by clicking on the green play button. Watch the console output on the bottom, the variable values and breakpoints on the right hand side. Unfortunately, Eclipse isn’t able to display the values of vectors or even vector fields.
You can walk through the code line by line while Eclipse emphasizes the line of the file it is currently reading. Use step into and step over buttons as well as breakpoint to navigate through the code.
7.1 Debugging in Parallel
Eclipse PTP - Parallel Tools Platform - more information in HowTo debugging
8 Profiling with gProf and Linux Tools
Profiling allows you analysis of your program in matters of usage of memory or frequency and duration of function calls aiming the optimization of your code.
For profiling OpenFOAM® recompile OpenFOAM® in Prof mode. Therefore change the compiler settings in OpenFOAM/OpenFOAM-1.6.x/etc/bashrc to Prof with WM_COMPILE_OPTION:=Prof and compile OpenFOAM® using ./Allwmake. This will take a few minutes.
In Prof mode run your application on a suitable test case for a while (as profiling is based on statistics) until your solver has finished and a gmon.out file has been produced. This file can be post-processed / visualized in Eclipse.
Install the Linux Tools Add-On for Eclipse and import your test case as project including the gmon.out file. Double-click on gmon.out and chosse the right associated binary for visualization.
Gprof view shows you which parts of your programm are most time consuming in a number of ways, e.g. samples per file, samples per function, samples per line or function call graph. It is also possible to create charts from your data.
9 Annotations and hints
9.1 Eclipse and python
Installing pydev, the python extension, enables Eclipse to define python projects and even use python with pyFOAM / OpenFOAM.
Therefore download the current pydev .zip-file (version 1.5.4 is recommended) from the sourceforge http://pydev.org/download.html. Unzip the file in the dropins folder and restart Eclipse. (for Eclipse 3.4 or 3.5)
For first steps follow the Getting Started Guide on http://pydev.org.
Alternative installation via Install new software:
- Select Help -> Install new software
- Click on Add Button
- Set pydev as name
- Enter http://pydev.org/updates as location
- Select ok and wait till site was contacted
- pydev is now available as installation option, select it, click on next and acknowledge everything
- Download and install will be executed
- pydev is available after restarting Eclipse
After installation a new project type pydev may be selected. Please make sure that upon creation Eclipse lists your pyFOAM project as pydev project. Otherwise the wrong indexer may be used. If so right click your project in the projects tab, select the entry pydev and set as pydev project. This will link the project with the python backbone.
9.2 Working in parallel with the terminal
You can still work on your project in the console, but if you then switch to Eclipse again, don't forget to refresh your workspace (F5). This may take a few seconds.
9.3 Increase Java heap space for Eclipse
If you get out-of-memory errors from Eclipse you may have to increase Java heap space for Eclipse in the eclipse.ini file, which manages start options for Eclipse. This error may occur if your OpenFOAM project is to big in size. For further information have a look at: http://wiki.eclipse.org/Eclipse.ini
For example increase the heap space to 1024 MB and minimum size of 256 MB, PermGenSize is 1024 MB.
-showsplash org.eclipse.platform --launcher.XXMaxPermSize 1024m -vm /opt/sun-jdk-1.6.0.02/bin/java -vmargs -Xms256m -Xmx1024m
Use top command for watching heap space usage in linux console.
9.4 Limit the number of sources
It is advisable to keep the number of projects per workspace small. If you include a large number of projects with many sources the start up and usage will slow down due to the indexer thread. You can work with multiple workspaces, Eclipse will ask you at start up which you want to use, its also possible to spread a project over multiple workspaces by importing (don't copy!) it in several workspaces.
9.5 Further information
- Eclipse homepage: http://www.eclipse.org
- Eclipse CDT Wiki: http://wiki.eclipse.org/index.php/CDT
- Eclipse tutorial: http://www.cs.umanitoba.ca/~eclipse/7-EclipseCDT.pdf
- All this information in a presentation: eclipseTutorial.pdf
- A collection of instructional screencasts: Eclipse and Java Video Tutorials at SourceForge (you probably can ignore the ones about Java)
10 Groups on extend-project
- OpenFOAM®-Development group: Integrated Development Environment (IDE) for OpenFOAM®
All about using IDEs for OpenFOAM® development and debugging in a faster and more comfortable way...
11 Training Session from 6th OpenFOAM Workshop: Integrated Environment Development (IDE) Eclipse for OpenFOAM
Assessing the Performance of bubbleFoam by Astrid Mahrla and Holger Marschall
held on 13 June 2011 - OpenFOAM University at 6th OpenFOAM Workhop, PennState University, State College, Pennsylvania
In this session programming will be performed introducing Eclipse as an Integrated Development Environment (IDE) for C++, which allows not only effcient programming, but also comfortable debugging in OpenFOAM. As a result of this session, the model capacities of bubbleFoam a solver for bubbly flows based on the Eulerian-Eulerian two-fluid model will be considerably extended to the cutting-edge of state-of-the-art, holding all drag and non-drag force models that have to be considered nowadays. These forces essentially characterize the fluid dynamics of the two-phase flow system present in bubbly systems.
Material
- Scriptum: Download File:Eclipse4OpenFOAM-handout.tar
- Presentation: Download File:Eclipse4OpenFOAM-slides.tar
- Test Case: Download File:CylindricBubbleColumn.tar
-- by A. Mahrla, 5 May 2010
-- updated by A. Mahrla, 22 September 2011
