Skip to content

Eclipse

Jump to bottom
Michał Wichrowski edited this page Oct 8, 2021 · 24 revisions

The Eclipse Integrated Development Environment and how to set up deal.II in it

About Eclipse

Eclipse is, today, the integrated development environment (IDE) that is likely most widely used around the world. It was originally developed for large-scale, industrial projects written in Java, but it has since been extended by plugins for virtually any other programming language, as well as many many modeling tools (for example, to name just one, for UML diagrams). For the purpose of deal.II, the C++ plugin (the Eclipse CDT) is the basis for the steps described below. The advantages of using a modern IDE described at the top of the page on [are equally valid for Eclipse, or course.

Eclipse with the C++ plugin included can be downloaded from the download page available via http://www.eclipse.org/ by choosing "Eclipse IDE for C/C++ Developers"(Download->Download Packages, direct link: https://www.eclipse.org/downloads/packages/). You will have to specify the operating system from the "download links" list to get the proper binaries for your operating system. Alternatively, a generic Eclipse can be used, but the Eclipse CDT (C/C++ Development Tools, the C++ plugin for Eclipse) has then to be installed separately. Eclipse offers automatic git integration: just clone a git repository and add it as a project.

Using an integrated development environment such as Eclipse is difficult to learn by just reading something about it. It's best learned by doing or watching someone else do it. To this end, take a look at training videos 7, 8, 8.01, and 25 at https://www.math.colostate.edu/~bangerth/videos.html .

A note upfront on using Subversion and Eclipse

If you will want to use subversion or some other version control system for the project you are about to set up, you first need to install the Eclipse plugin that can handle this -- installing the plugin later will not convert the project into one that uses subversion, even if the directories in which it is located have previously been created by subversion. See below for how to install the subversion plugin.

Useful tricks

Eclipse is a powerful piece of software offers a lot of customization option, but you have to know what you are looking for. Below we present a few suggestions that might make it more friendly.

Changing heap size

The settings file eclipse.ini is located right next to Eclipse executable. You might want to increase heap size by changing the following options:

  • -Xms256m
  • -Xmx2048m The numbers indicate heap size in megabytes. You can control heap status Window > Preferences > General and enable Show heap status and clicking OK.

Completely cleaning up the source directory

Eclipse creates two files in the source directory: .cproject, .project and .settings. If you want to completely clean up the project settings completely, be sure to remove those files after the project is removed from the workspace.

Removing Eclipse workspace lock

Eclipse 'locks' workspace directory to ensure only one instance is using it at the time. If Eclipse crashes sometimes the lock is not removed, and the workspace cannot be used. To resolve that issue delete .lock file located in YOUR WORKSPACE DIR/.metadata

Alternative dark themes

If you do not like the built-in dark theme of Eclipse, you can try installing plugins for a better experience: https://marketplace.eclipse.org/category/free-tagging/theme

After installing the plugin go to Window->Preferences and search for Appearance.

Filtering Problems/Tasks by active project

In the lower frame, there are Problems and Tasks tabs. By default all issues from the current workspace are showed that might not be optimal. To change that, locate buttons on the upper-right side of the tab, click on Filters, disable Show all items and enable whatever you want.

Setting up a workspace in Eclipse using cmake4eclipse

The following instructions are based on this answer: https://stackoverflow.com/questions/9453851/how-to-configure-eclipse-cdt-for-cmake/38716337#38716337 , cmake4eclipse help (https://github.com/15knots/cmake4eclipse#readme) and this thread: https://groups.google.com/g/cmake4eclipse-users/c/r5YfWUMd2iM. The following instructions have been tested on Eclipse 2021-06 (4.20.0).

WARNING: If you set up your project this way, DO NOT use CMake built-in generators, as it will modify the Eclipse project files in the source directory, likely resulting in conflicts and confusing the indexer.

Setting deal.II itself as a project from scratch

From the Eclipse menu choose Help->Eclipse Market place... and search for cmake4eclipse, install it. First, add deal.II itself as a project. This will force the Eclipse indexer to go through the entire library.

WARNING: Do not create a C/C++ project, since that takes you down the core-build road!

  1. Go to File-> New -> Project...

  2. From C/C++ section choose C++ project, click Next.

  3. Set a meaningful project name, uncheck Use default location and specify the location of deal.II source directory. In Project type select CMake driven ->Empty project and in Toolchain menu select CMake Driven. Click Next.

  4. Eclipse sometimes is not aware of what is your compiler. To fix/check that:

    1. Click Advanced Settings, agree to override existing project settings.
    2. Go to C/C++ Build-> Settings, check if the Command field is filled correctly, in case if it is <unnamed> change it to g++ or mpicc (or whatever your compiler is).
    3. In C/C++ General-> Preprocessor Inlclude go to providers and uncheck Use global provider shared between projects (because global provider means compiler command will be <unnamed>, and thus Eclipse will fail to find compiler configuration)

  5. After finishing setting up the project the Eclipse Indexer will start working. Since CMake have not been invoked yet there is no point in doing that. On the right-bottom corner of the window, there will be a green square bouncing horizontally indicating. Click on it, it will open the Progress window. Terminate ongoing Indexer process.

  6. Build deal.II. This will invoke CMake to generate compile_commands.json file inside the build directory that is later parsed by cmake4eclipse and used to provide paths and symbols for the Eclipse Indexer.

  7. You can check the paths and symbols provided by cmake4eclipse in Project->Properties->C/C++ General-> Preprocessor Inlclude. Both CMAKE_EXPORT_COMPILE_COMMANDS Compiler Built-ins and CMAKE_EXPORT_COMPILE_COMMANDS Parser should be now drop-down list as in the picture below. Notice the triangles near CMAKE_EXPORT_COMPILE_COMMANDS*

Advanced CMake settings

In Project->Properties->C/C++ Build -> Cmake4Eclipse you can tweak your CMake settings. In the Symbols tab you can specify cmake variables. For example, you can add click add, put DEAL_II_WITH_MPI in Variable name, set type to Bool and put ON in Value field to enable deal.II with MPI.

Setting preconfigured deal.II as a project

If you have already set up deal.II inside, say, build directory (that is a subdirectory of deal.II source dir) you may use those settings.

  1. Go to the build directory and execute the command:
cmake . -DCMAKE_EXPORT_COMPILE_COMMANDS=ON

This will force CMake to generate the compile_commands.json file.

  1. Repeat steps 1 - 4 from above.

  2. In Advanced Settings from step 4 go to C/C++ Build-> cmake4eclipse, set the configuration you want to modify. Inside Build Output Location frame, set Folder to "build/" (or whenever you built deal.II). In frame Pre-populate CMake cache entries from file set "build/CMakeCache.txt". Click Apply before going to other tabs (somehow the changes there are not saved otherwise)

  3. Continue the process as described above.

Unfortunately, you will have to rebuild deal.II (but fortunately not reconfigure) since Eclipse during the first build invokes make clean. It only happens once. The author of this section is not aware how to disable this behaviour.

Setting up a project depending on deal.II

Repeat the steps above for your project.

You may want to go to Project->Properties->Project References and check deal.II (if you set it up as a project before). We recommend that even if you do not intend to change the deal.II code (Eclipse will be able to provide you documentation and browsing the library code will be much easier).

If you set up your project directly in Eclipse, deal.II might not detected (message will appear in the Console window). In that case, go to Project->Properties->C/C++ Build -> Cmake4Eclipse, in Symbols tab, click Add... inside CMake cache entries to create. Set variable name to deal.II_DIR, type to PATH and specify wherever your deal.II installation is.

Setting up a project depending on deal.II using CMake built-in generators

The easiest way to get Eclipse to understand your project is to let CMake generate an Eclipse project for you, assuming you are using CMake. To this end, go to the source directory (using the step-22 example again) and say

  cmake -G "Eclipse CDT4 - Unix Makefiles" -DDEAL_II_DIR=/path/to/deal.II .

This generates not only a Unix Makefile, but also an Eclipse project file. You can get Eclipse to use it by selecting from the menu "File > Import...", then choosing "General > Existing Projects into Workspace". Click on "Next", and in the next dialog window select as the root directory the directory where you ran CMake above. After selecting this directory, Eclipse should show you the name of the project under "Projects". Simply click on "Finish" to let Eclipse choose it. It will then automatically know where to find header files, about build targets, etc.

To build the executable, go to the "Make target" tab (usually located in the right sub-window) and double-click on "all". In the "Console" tab (usually located in the bottom sub-window) you can view the commands being executed to build your program.

You may still have to set up, run and debug launches if you want to run or debug the executable so built, however.

Setting up a project using deal.II by hand

After starting Eclipse for the first time, you will be asked to choose a workspace. Accept the default. Then, you get a screen that provides you with a number of introductory options such as a tutorial, the help pages, etc. Take a look at these or click on the icon to get to the Workspace right away (where you will also land when calling Eclipse for the second or later times). Then follow these steps, shown below taking the step-22 tutorial as an example of any free-standing program that uses deal.II (these steps are also demonstrated in video #7 linked to above):

  • Create the Eclipse project:
    • From the main menu bar select: "File > New > Makefile Project with Existing Code" (alternatively, you can use the right-click context menu in the "Project Explorer" sub-window on the left)
    • Browse for the directory which has the code of your project, examples/step-22 in this example, select "Linux GCC" as the "Toolchain for Indexer Settings", then press Finish. The project now exists for Eclipse, and it should allow you to edit files, use auto-completion, etc. Go ahead by either opening by hand one of your project's .cc files or by hitting Shift-Ctrl-R and start typing the name of one of your files, for example in the current context step-22.cc. This should open the file and allow you to edit it. However, Eclipse will show swiggly lines under any deal.II symbol, the deal.II header files, etc. The next step is to teach Eclipse where to find the deal.II header files so that it knows about the deal.II classes, functions, etc. To this end, right-click on the newly created project in the "Project Explorer" subwindow on the left and choose "Properties" at the very bottom. Then:
    • Select "C/C++ General > Paths and Symbols" by expanding the tree view under "C/C++ General"
    • Select "GNU C++" and click on "Add..." on the right
    • Select "Add to all languages", just to be on the safe side
    • From the "File system..." select the include directory of an installed version of deal.II
    • Click "OK" as often as necessary to close all dialog windows.
    • If your project depends on other external libraries, you may wish to repeat this step for all include file directories of these projects. Eclipse should have removed the swirly lines from under all header files, but it will likely not recognize the deal.II classes and functions yet, as indicated by the lines under these names and the red marks at the right margin of the editor sub-window. To achieve this, just close the editor sub-window and open the file again. You can test that Eclipse has found everything by putting the cursor into the editor window where you opened step-22.cc and in one of the member functions start typing something like triangulation.exec and then hitting Ctrl-Space to see what auto-completions Eclipse proposes. It should, among others, at least propose triangulation.execute_coarsening_and_refinement based on its knowledge that the member variable triangulation is of type Triangulation<dim>.

Note: Eclipse will use a very large amount of memory to index all of the symbols deal.II provides, on the order of several gigabyte. If you do not have that much memory, you can limit how much it uses by excluding the include/deal.II/bundled directory from indexing, which may contain in particular the BOOST header files that are exceedingly large. This can be done with a resource filer, as described at http://help.eclipse.org/kepler/index.jsp?topic=/org.eclipse.platform.doc.user/concepts/resourcefilters.htm .

The next step is to teach Eclipse how to compile your project. To this end, it needs a Makefile. If you are writing the Makefile yourself, all is well. If you are using CMake to build your project in the same directory as the source files are (that's the setup we use for the tutorial programs), then you need to run CMake first to produce a Makefile. These are the next steps then:

  • Configure the build:

    • As above, highlight the new "step-22" project, then go to "Project > Make target > Create" and enter "step-22" into the respective dialog field.
    • Alternatively, you can right-click on the "step-22" project name in the left sub-window and go to the "Make targets > Create" entry.
    • Afterwards select "Project > Properties" from the main menu bar and in the corresponding dialog select "C/C++ Build" from the left panel (i.e., the actual entry, not the down-arrow next to it). Then select the "Behaviour" tab to set the desired build target, here "step-22", at "Build (incremental Build)" text box. The correct entry for "Clean" is simply "clean" (this is used to remove all generated files in this directory).

  • Configuring the binary to run and debug ("launches"):

    • From the main menu bar select: "Run > Run configurations" to open the "Run Configuration" window
    • From the window, double click "C/C++ Application" on the left panel to create a new run configuration, or highlight "C/C++ Application" and click on the hardly-recognizable "New launch configuration" button at the top of the selection list on the left. Then, unless it is already there, type the executable name that is produced by the Makefile in the field "C/C++ Application", again "step-22" in this example.
    • If you have an application that requires an input file, then the name of this input file can be entered in the other tabs.
    • Close the dialog, and test whether the application runs as intended by clicking on the green right triangle button at the top of the primary window, roughly in the middle. The output of the program should again appear in the "Console" tab of the subwindow at the bottom.

At this point you should have a complete project you can edit, compile and run. The screen should look roughly like this after opening the step-22.cc file (my project names are prefixed with the name of the machine, thus the "ultra450." prefix to everything; also, when I created this snapshot, I had not set the include paths correctly and the red swirly lines under many symbols should not be there for you):

''

Debugging with Eclipse

Once you have set up a launch configuration for an application as described above, you can also debug this application. (One of the video lectures referenced above also shows you how to do this.) To this end, hit the small green "Bug" icon just to the left of the "Run" icon described above. This will build the executable (if it isn't up to date) and then move all of Eclipse into "Debug Perspective", as shown here:

''


"Debug perspective" gives you an entirely different view on the program as the "Code perspective" you have seen before. (You can toggle between the two perspectives using the icons at the top right of the Eclipse main window.) In particular, what you primarily get to see is the call stack at the top left, a view of all local variables at the top right, the source at the center left, an outline of the current file at the center right, and the console output of your program at the bottom. All of these sub-windows can be resized, of course. Some of these sub-windows have other tabs as well that you can explore, and if you don't need one sub-window for a moment, then click on the triangle pointing down to minimize it -- it will end up as an icon at the left margin, right margin, or bottom right of the main window (depending on where the sub-window was located before) from where it can be restored.

Using the symbols in the "Debug" sub-window at the top left (or the menu entries and corresponding keyboard shortcuts listed in the "Run" menu"), you can now step through the program, inspect the current state of your program at the top right by observing the values of local variables, and set breakpoints by going to certain source locations and right-clicking onto the code line you want to set a breakpoint on.

Setting up deal.II as a development project in itself

If you want to work on the deal.II sources themselves, rather than just use them for your own project, then use the following steps:

  • Select menu item "File > New... > Makefile project with existing code" and in the dialog that opens give the project a name (e.g., "deal.II") and enter or select the path to the deal.II directory into which you have previously unpacked the library. In the "Toolchain for Indexer Settings" select "Linux GCC". Then click "Finish".

You will notice that an icon for the next project has appeared in the "Project Explorer" sub-window on the left side of the Eclipse main window. The icon can be expanded using the little down-arrow on its left to see the directory tree underneath and you can try to go down into it to open a file just to see how it works. You will also notice that a progress bar at the center bottom of the Eclipse window is indicating that Eclipse is reading and parsing all the files in this directory tree so that the editor can offer you auto-completion and similar things.

Note 1: The steps above only set up deal.II as a project inside Eclipse, allowing you to edit files and telling Eclipse where to find symbols so that things like auto-completion work. However, they do not allow you to build and install deal.II from inside Eclipse. Eclipse does in principle allow you to set up these things (see above, for how to do this on a project that uses deal.II), but it is difficult to do when building in a directory other than where the source files are located, as we suggest in the deal.II installation instructions. Consequently, if you want to develop deal.II, not just use it, then you still want to build and install from the command line.

Note 2: The steps above allow you to use Eclipse to edit deal.II files and most of it will work just as expected. However, there is one snag: some parts of the code of deal.II is guarded by things like

  #ifdef DEAL_II_WITH_TRILINOS
  ...
  #endif

In particular, this is the case for all of the Trilinos and PETSc wrappers, and parts of the MPI stuff. The problem is that whether this preprocessor symbol is defined or not is something that can not be determined by looking at the source directory we have taught Eclipse about: it is something that is determined in a file config.h in the build directory (of which there may in fact be more than one per source directory). Consequently, by default, Eclipse doesn't see the #define DEAL_II_WITH_TRILINOS anywhere and thus never offers you to auto-complete any of the Trilinos, PETSc or MPI stuff. This is annoying. If you want to develop stuff where this is an obstacle, you can provide Eclipse with additional include paths to search, as explained above when setting up external projects. You can do this to provide Eclipse with a path where it can find a deal.II/base/config.h file (typically, the install directory where you install the version you are currently developing) that has the requisite #defines so that Eclipse also provides you with information about the otherwise unavailable classes.

  • The next step is to set up deal.II as a project Eclipse knows how to compile. To this end, select (highlight) the deal.II project with the mouse in the "Project Explorer" sub-window. Then go to "Project > Make Target > Create" and enter a Makefile target name. You can get the existing target names by running make on the command line in the deal.II directory -- the two most common ones are "all" and "online-doc", along with "debug" and "optimized". You can repeat creating targets several times.

  • To see which targets now exist for Eclipse, note the "Make targets" tab in the right sub-window (the other tabs are "Outline" and "Task list", unless you have added more tabs to this sub-window using "Window > Show view").

  • You can let Eclipse build a particular target by double-clicking on a target. The corresponding output of the make command and the compilers it calls will then end up in the "Console" tab in the bottom sub-window.

Everything you've done so far is visible in the following screenshot:

''


Note: If a particular tab of a sub-window is not where you expect it, look around in the other sub-windows. They can be drag-and-dropped into the place where you want them to be. If they're not there altogether, take a look at the list of views in the "Window > Show view" menu entry for what's available!

A final, useful, modification if you have more than one processor in your system is to enable parallel builds. To this end, select the menu entry "Project > Properties...", then select "C/C++ Build" and in the "Builder Settings" tab uncheck the box that says "Use default build command". This enables editing the text field that follows and allows you to replace the default command make by make -j8, for example, if you want to compile with 8 parallel compile jobs.

Some useful keyboard shortcuts

I found the following key combinations useful, beyond the usual ones to open or save files, etc:

Editing
Jumping around in code
Ctrl-Shift-R Open resource: type the name of a file and get it opened. Note that the search window allows you to use wildcards such as `*` if you only want to type part of a name.
Ctrl-Shift-H Open type: type the name of a type/class and get it opened. Note that the search window allows you to use wildcards such as `*` if you only want to type part of a name.
Ctrl-Shift-T Open element: type anything (class name, function name) and get a list of anything that matches to select from
Ctrl-Alt-I Open the include browser: Show a list of all include files used in the current file. Right clicking on any of the shown include files allows opening them.
Ctrl-O Outline: Provide a list of all things that are happening in this file, e.g. class declarations and function definitions, include directives, etc; the dialog that appears allows you to start typing a name, reducing the list to all those that match.
F3 Jump to declaration of a function or variable if the cursor is currently in a function definition
Ctrl-Shift-Down Jump to next function
Ctrl-Shift-Up Jump to previous function
Ctrl-L Goto line
Crtl-W Closes current "tab".
Alt-Left Jump to previous used "tab". This even opens a previously closed file.
Alt-Right Jump to next "tab"
Searching and replacing
Ctrl-J Incremental find: start typing and see what fits so far
Ctrl-F Find and find/replace
Ctrl-K Find next
Other things
Ctrl-Space Call auto-completion assistant
Alt-/ Auto-complete. If multiple names match the already typed text, then you can cycle through them by hitting Alt-/ multiple times.
Ctrl-Shift-Space In an expression of the form "object.member()" or "function()" with the cursor in the parentheses, opens a context menu that shows the order and types of arguments that go there.
Ctrl-/ Comment in/out selected text or current line
Ctrl-Shift-F Automatic indent highlighted lines of code.
Ctrl-_ (Ctrl-Shift-Minus) Split/unsplit editor view horizontally
Ctrl-{ (Ctrl-Shift-[) Split/unsplit editor view vertically
Ctrl-3 Quick access: start typing and it shows all menus, editors, views, commands that match that substring
Ctrl-Shift-L Show all key bindings, e.g,. for example to learn about more key shortcuts
Debugging
F6 Step over (gdb's "next")
F5 Step into (gdb's "step")
F7 Step return (gdb's "finish")
F8 Resume (gdb's "continue")
Running a program
Ctrl-B Build (call make)
Ctrl-F11 Run
F11 Run program in the debugger; you may want to set breakpoints beforehand, for example by right-clicking with the mouse on the left sub-window margin next to a particular line in the source code
Working with subversion (works both in file editors as well as the C/C++ project view)
Ctrl-Alt-L Show diffs
Ctrl-Alt-C Commit
Ctrl-Alt-U Update from repository
Ctrl-Alt-P Create a patch from local changes

Configuring Eclipse

Eclipse can be configured in a myriad different ways, to the point where one sometimes finds oneself wishing that there were less bells and whistles. Be that as it may, there are many useful things that may take a while to discover but that really make life easier. Below is a list of things that integrate working with big software projects like deal.II better into the existing workflows of version control, documentation, etc.

Showing line numbers and dealing with tabs

Since deal.II assertions show which line of a file triggered an error, it is often useful to configure Eclipse to show line numbers next to each line of a file that's open in an editor. To do this, go to "Window > Preferences", then select the down-arrow of "General", in the sub-tree that then expands select the down-arrow next to "Editors" and click on "Text editor". In the dialog to the right of the window, click the checkbox called "Show line numbers".

''


In the same dialog, there is also a setting for the tab width. In the deal.II source code, we use a tab width of 8, but Eclipse by default uses 4, leading to an occasionally awkward display of indentation levels. Thus, set it to 8. Finally, since different editors have a habit of interpreting the tab size differently (some assume that a tab equals 4 spaces, whereas others assume 8), it is worthwhile to simply disable the use of tabs altogether when editing code, and letting the editor fill any space it encounters using spaces. For this, check "Insert spaces for tabs".

Enabling code folding

Some people really like the editor to fold in code they aren't working on right now so that only that part that's relevant for the moment is visible (others just excessively use the "Outline" facility using the Ctrl-O shortcut). By default, the Eclipse folding settings are a bit awkward since it doesn't want to fold a whole lot, but this (like everything else) can be configured. To this end, go to "Window > Preferences" and select the C/C++ tab and under it the "Editor > Folding" sub-tab. You can select which regions of a code can be folded:

''

The buttons under "Initially fold these region types" allow you to set which regions should be folded in whenever you open a file the first time; I have chosen to see the entire file but you can obviously choose a different set.

Once selected as above, you can fold in or out certain parts of the code by clicking on the little "-" or "+" buttons in the gray area on the left side of an editor window, right next to line numbers if you have enabled them as shown above.

Integrating Eclipse and Subversion

deal.II and many of its subprojects use http://subversion.apache.org Subversion as the Version Control System of choice. Eclipse has a plugin that allows using Subversion for all the files one wants to work on; the plugin is called Subversive and you need to install it before creating any project (see above) you want to use this plugin for.

In order to install Subversive, go to menu entry "Help > Install new software" and choose the site in the "Work with" dialog at which the plugins for this version of Eclipse can be obtained. At the time of writing this text Indigo was the current Eclipse version, and the site was "Indigo - http://download.eclipse.org/releases/indigo". It takes a while (a couple of minutes on my system) for Eclipse to figure out all the packages that are available but when it does you should be able to find the Subversive packages in the "Collaboration" tab that you can expand using the down arrow. Select them all and then hit the appropriate buttons to get them installed. Half-way through the process, Eclipse will ask you which "Subversive Connector" you want to install. These connectors are apparently specific for the particular subversion release you have (which you can find out by calling svn --version on the command line). Pick the one that matches your version best.

Once you have the Subversive plugin installed, create an Eclipse project as discussed at the top of this page. The project explorer panel should then look somewhat like this, displaying the revision number next to each file or directory:

''

All the usual subversion operations (adding a file or directory, updating it from the repository, committing, diffing, annotating, or showing a history) can then be obtained through one of two ways:

  • If you are in an editor window, right-click into the window to get the context menu and from there go to the sub-menu called "Team".
  • Right-clicking on a file or directory in the "Project Explorer" panel on the left (i.e., the one shown above) and then again selecting the sub-menu "Team".

Maybe confusingly, however, the option to see the diffs of a file/directory against the one that's in the repository is not found in the "Team" sub-menu, but in the "Compare with" sub-menu.

Integrating Eclipse and Doxygen

Doxygen is one of the most important tools for generating high quality documentation for C++ software, and it is the tool by which all of deal.II's documentation is generated. Thus, it would be nice if Eclipse could help write this documentation, and indeed it can. To this end, tell Eclipse that we want to be able to write Doxygen comments, by going to the "Window > Preference" menu entry and then selecting the "C/C++" tab and "Editor" subtab as shown here:

''

Then select "Doxygen" as the "Documentation tool" in the bottom part of the panel on the right, as shown above.

With this setting so chosen, we can start editing and see how it can help us. To this end, let's assume we have written the following function declaration:

''

We may want to document it using the usual Doxygen markup. So go to the line before the function, type /** and hit enter. Eclipse will then automatically expand the comment to the following:

''

You can then start filling in the documentation for the function as a whole, the two function arguments, and the return type, using all the markup options Doxygen provides.

Code style issues

Eclipse can be configured in more ways than one can count. One issue is configuring the indentation style. As a historical accident, deal.II is using an indentation style that doesn't match pretty much any other style that is around, but it can be approximated using Eclipse's settings.

Deal.II uses clang-format for indentation. This is not natively supported by Eclipse, but fortunately, a suitable add-on exists. From the Eclipse menu choose Help->Eclipse Market place... and search for CppStyle. This allows you to run clang-formant when Ctrl+Shift+F is pressed. It also has an option to run clang-format on save. It uses settings from the .clang-format file (custom for every project). You can configure CppStyle globally from Window->preferences and then C/C++ -> CppStyle (or just type CppStyle in search bar). Project-wise settings are also possible.

There is also a way to configure Eclipse without installing add-ons:

  • Highlight the deal.II project you have created above in the "Project Explorer" sub-window.
  • Go to "Project > Properties" from the main menu, or right-click on the project and choose "Properties" in the context menu.
  • Then go to expand the "C/C++ General" sub-tree by clicking on the down arrow next to it and select "Code style".
  • In the panel on the right, you can click on "Configure Workspace Settings..." to get a dialog in which you can edit an existing coding style or create a new one.
  • You can import the following style: stylefile.xml
  • Alternatively, create a new one and choose the "GNU" style as the basis for this new style and follow the instructions below.

Modify the entries under the various tabs of this dialog as shown in the following set of pictures (click on the pictures to get larger versions):

''

''

''

''

''

''

''

''

''

Setting up Eclipse with Parallel Tools Platform (PTP)

Section currently under development. Please be patient.

What PTP is?

PTP is a set of tools for developing, debugging and profiling MPI applications. Instructions for installation into existing Eclipse can be found here. Make sure you're trying to install the correct PTP version for your Eclipse (7.0 for Kepler, 6.0 for Juno, 5.0 for Indigo). Most of the installation issues are described in PTP release notes v.7.0.

Installing from package

These instructions have been tested under Ubuntu 12.04 If you were not able to install PTP into existing Eclipse (or you can't find PTP perspectives in Window->Show Perspective -> Other - it sometimes happens), maybe it would be easier to download a complete package from Eclipse download site. "Eclipse for Parallel Application Developers Eclipse for Parallel Application Developers" is the package that you have to download. Untar it wherever you want, open terminal, navigate to Eclipse folder and run ./eclipse (it is safe to do it this way - to make sure that Eclipse has some environmental variables as in terminal).

SDM - Scalable debug manager

Debugging parallel programs is not easy - especially when the error occurs only in parallel executions. SDM allows debugging parallel programs in similar way that standard Eclipse debugger can help you improve non-mpi applications. To use SDM you have to install it on target machine. Here are instructions how to do it. Compiling from source should work (tested on Ubuntu), but if you have some trouble with it, you should find compiled PTP in ptp-sdm-7.0.x.zip package from here: [http://download.eclipse.org/tools/ptp/updates/kepler] (directory sdm/org.eclipse.ptp.OS_7.0.x.yyyymmddhhmm , where OS is operating system and 7.0.x.yyyymmddhhmm is PTP release ).

Setting up project with parallel run configuration

Set up you project in the same way as for standard deal.II programs. If you have workspace folder from other versions of Eclipse you can reuse it. Now you will only have to configure parallel runs.

Local projects (only with Eclipse Kepler with PTP 7.x)

Go to Run->Run Configurations. Select Parallel Application and click on "New lauch configuration"(PICTURE). Specify your MPI version from drop-down list and select Local in connection type. You will be asked to confirm connection to local system, click Yes.(PICTURE) Now there will be some other option available: (PICTURE) Go to applications and specify executable in "Application program". Click "Apply". Now you can test your configuration by pressing "Run", or just click "Close". New run configuration will appear in drop-down menu near Run button at the top of a screen.

If you run configuration is working, you can set up debugger. Go to Run->Debug Configurations. In Parallel Applications will be your run configuration. Now you only have to set SDM executable path - go to Debugger tab.(PICTURE) If you have installed SDM with custom prefix, specify path to SDM. The number of MPI processes can be increased in the Resources tab.

Debugging a parallel program

From the drop-down list near bug, icon selects your debug configuration. You will be asked to confirm opening Parallel Debug perspective, click yes. The following view will appear: (PICTURE)

The main difference between the default Eclipse debugger is "Parallel Debug" tab. The diamonds represent processes, green means that the process is running, yellow - suspended, red -terminated. You can select one process by double click. The black square indicates if process is selected, only selected processes are displayed in "Debug" tab. From Debug tab you can debug each process like serial one, you can also suspend a group of processes in "Parallel Debug" tab.

More informations can be found in PTP help and tutorials.

Clone this wiki locally