b55e3f367da150536c25115ae1353012ad3c7638
[dealii.wiki.git] / Eclipse.md
1 # The Eclipse Integrated Development Environment and how to set up deal.II in it
2
3 **Note: The following page is written with the CMake build system in mind that will be used starting with deal.II 8.0.**
4
5 # About Eclipse
6
7 [Eclipse](http://www.eclipse.org) is, today, the integrated development
8 environment (IDE) that is likely most widely used around the world. It was
9 originally developed for large-scale, industrial projects written in Java, but
10 it has since been extended by plugins for virtually any other programming
11 language, as well as many many modeling tools (for example, to name just one,
12 for UML diagrams). For the purpose of deal.II, the C++ plugin (the
13 [Eclipse CDT](http://www.eclipse.org/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.
14
15 Eclipse with the C++ plug in included can be downloaded from the download page
16 available via http://www.eclipse.org/ by choosing "Eclipse IDE for C/C++
17 Developers". You will have to specify the operating system from the "download links"
18 list to get the proper binaries for your operating system.
19 Alternatively, a generic Eclipse can be used, but the Eclipse CDT (C/C++
20 Development Tools, the C++ plugin for Eclipse) has then to be installed
21 separately.
22
23 Using an integrated development environment such as Eclipse is difficult to
24 learn by just reading something about it. It's best learned by <i>doing</i> or
25 watching someone else do it. To this end, take a look at training videos 7, 8
26 and 25 at http://www.math.tamu.edu/~bangerth/videos.html .
27
28 *Overview:*
29 <wiki:toc />
30
31
32 # A note up front on using Subversion and Eclipse
33
34 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 about how to install the subversion plugin.
35
36
37
38 # Setting up a project using deal.II by hand
39
40 After starting Eclipse for the first time, you will be asked to choose a workspace. Accept the default. Then, you
41 get a screen that provides you with a number of introductory options such as a
42 tutorial, the help pages, etc. Take a look at these or click on the icon to
43 get to the Workspace right away (where you will also land when calling Eclipse
44 for the second or later times). Then follow these steps, shown below taking the
45 step-22 tutorial as an example of any free-standing program that uses deal.II
46 (these steps are also demonstrated in video #7 linked to above):
47
48   - Create the Eclipse project:
49     - 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)
50     - 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.
51     The project now exists for Eclipse, and it should allow you to edit files,
52     use auto-completion, etc. Go ahead by either opening by hand one of your
53     project's `.cc` files or by hitting Shift-Ctrl-R and start typing the
54     name of one of your files, for example in the current context
55     `step-22.cc`. This should open the file and allow you to edit it.
56     However, Eclipse will show swiggly lines under
57     any deal.II symbol, the deal.II header files, etc. The next step is to
58     teach Eclipse where to find the deal.II header files so that it knows
59     about the deal.II classes, functions, etc. To this end, right-click on the
60     newly created project in the "Project Explorer" subwindow on the left and
61     choose "Properties" at the very bottom. Then:
62     - Select "C/C++ General > Paths and Symbols" by expanding the tree view under "C/C++ General"
63     - Select "GNU C++" and click on "Add..." on the right
64     - Select "Add to all languages", just to be on the safe side
65     - From the "File system..." select the include directory of an installed version of deal.II
66     - Click "OK" as often as necessary to close all dialog windows.
67     - If your project depends on other external libraries, you may wish to repeat this step for all include file directories of these projects.
68     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>`.
69
70 *Note:* Eclipse will use a _very large amount_ of memory to index all of the
71 symbols deal.II provides, on the order of several gigabyte. If you do not have
72 that much memory, you can limit how much it uses by excluding the
73 `include/deal.II/bundled` directory from indexing, which may contain in
74 particular the BOOST header files that are exceedingly large. This can be done
75 with a _resource filer_, as described at
76 http://help.eclipse.org/kepler/index.jsp?topic=/org.eclipse.platform.doc.user/concepts/resourcefilters.htm .
77
78 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:
79
80   - Configure the build:
81     - As above, highlight the new "step-22" project, then go to "Project > Make target > Create" and enter "step-22" into the respective dialog field.
82     - Alternatively, you can right-click on the "step-22" project name in the left sub-window and go to the "Make targets > Create" entry.
83     - 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).
84
85
86   - Configuring the binary to run and debug ("launches"):
87     - From the main menu bar select: "Run > Run configurations" to open the "Run Configuration" window
88     - 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.
89     - If you have an application that requires an input file, then the name of this input file can be entered in the other tabs.
90     - 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.
91
92 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):
93
94 '<img width="800px" src="http://www.dealii.org/images/wiki/Eclipse-2.png" align="center" />'
95
96
97 # Debugging with Eclipse
98
99 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:
100
101 '<img width="800px" src="http://www.dealii.org/images/wiki/Eclipse-3.png" align="center" />'
102
103 <br>
104
105 "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.
106
107 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.
108
109
110 # Setting up a project using deal.II with CMake help
111
112 An alternative 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
113 ```
114   cmake -G"Eclipse CDT4 - Unix Makefiles" -DDEAL_II_DIR=/path/to/deal.II .
115 ```
116 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.
117
118 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.
119
120 You may still have to set up run and debug launches if you want to run or debug the executable so built, however.
121
122 # Setting up deal.II as a development project in itself
123
124 If you want to work on the deal.II sources themselves, rather than just use
125 them for your own project, then use the following steps:
126
127   - 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".
128
129 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.
130
131 *Note 1:* The steps above only set up deal.II as a project inside Eclipse,
132 allowing you to edit files and telling Eclipse where to find symbols so that
133 things like auto-completion work. However, they do not allow you to build
134 and install deal.II from inside Eclipse. Eclipse does in principle allow you
135 to set up these things (see above, for how to do this on a project that
136 <i>uses</i> deal.II), but it is difficult to do when building in a directory
137 other than where the source files are located, as we suggest in the deal.II
138 installation instructions. Consequently, if you want to <i>develop deal.II,
139 not just use it</i>, then you still want to build and install from the command
140 line.
141
142 *Note 2:* The steps above allow you to use Eclipse to edit deal.II files and
143 most of it will work just as expected. However, there is one snag: some parts
144 of the code of deal.II is guarded by things like
145 ```
146   #ifdef DEAL_II_WITH_TRILINOS
147   ...
148   #endif
149 ```
150 In particular, this is the case for all of the Trilinos and PETSc wrappers,
151 and parts of the MPI stuff. The problem is that whether this preprocessor
152 symbol is defined or not is something that can not be determined by looking at
153 the <i>source</i> directory we have taught Eclipse about: it is something that
154 is determined in a file `config.h` in the <i>build</i> directory (of which
155 there may in fact be
156 more than one per source directory). Consequently, by default, Eclipse doesn't
157 see the `#define DEAL_II_WITH_TRILINOS` anywhere and thus never offers you to
158 auto-complete any of the Trilinos, PETSc or MPI stuff. This is annoying. If
159 you want to develop stuff where this is an obstacle, you can provide Eclipse
160 with additional include paths to search, as explained above when setting up
161 external projects. You can do this to provide Eclipse with a path where it can
162 find a `deal.II/base/config.h` file (typically, the install directory where you
163 install the version you are currently developing) that has the requisite
164 `#define`s so that Eclipse also provides you with information about the
165 otherwise unavailable classes.
166
167   - 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.
168
169   - 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").
170
171   - 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.
172
173 Everything you've done so far is visible in the following screenshot:
174
175
176 '<img width="800px" src="http://www.dealii.org/images/wiki/Eclipse-1.png" align="center" />'
177
178 <br>
179
180 *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 avaiable!
181
182 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.
183
184
185
186 # Some useful keyboard shortcuts
187
188 I found the following key combinations useful, beyond the usual ones to open or save files, etc:
189
190
191 <table border="1" cellspacing="0">
192 <tr>
193 <th colspan="2" style="background-color:#ffff99;"> Editing
194 </th></tr>
195 <tr>
196 <th colspan="2"> Jumping around in code
197 </th></tr>
198 <tr>
199 <td>       Ctrl-Shift-R
200 </td><td> 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.
201 </td></tr>
202 <tr>
203 <td>       Ctrl-Shift-H
204 </td><td> 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.
205 </td></tr>
206 <tr>
207 <td>       Ctrl-Shift-T
208 </td><td> Open element: type anything (class name, function name) and get a list of anything that matches to select from
209 </td></tr>
210 <tr>
211 <td>       Ctrl-Alt-I
212 </td><td> 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.
213 </td></tr>
214 <tr>
215 <td>    Ctrl-O
216 </td><td>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.
217 </td></tr>
218 <tr>
219 <td>    F3
220 </td><td>Jump to declaration of a function or variable if the cursor is currently in a function definition
221 </td></tr>
222 <tr>
223 <td>    Ctrl-Shift-Down
224 </td><td>Jump to next function
225 </td></tr>
226 <tr>
227 <td>    Ctrl-Shift-Up
228 </td><td>Jump to previous function
229 </td></tr>
230 <tr>
231 <td>    Ctrl-L
232 </td><td>Goto line
233 </td></tr>
234 <tr>
235 <td>    Crtl-W
236 </td><td> Closes current "tab".
237 </td></tr>
238 <tr>
239 <td>    Alt-Left
240 </td><td>Jump to previous used "tab". This even opens a previously closed file.
241 </td></tr>
242 <tr>
243 <td>    Alt-Right
244 </td><td>Jump to next "tab"
245 </td></tr>
246 <tr>
247 <th colspan="2"> Searching and replacing
248 </th></tr>
249 <tr>
250 <td>    Ctrl-J
251 </td><td>Incremental find: start typing and see what fits so far
252 </td></tr>
253 <tr>
254 <td>    Ctrl-F
255 </td><td>Find and find/replace
256 </td></tr>
257 <tr>
258 <td>    Ctrl-K
259 </td><td>Find next
260 </td></tr>
261 <tr>
262 <th colspan="2"> Other things
263 </th></tr>
264 <tr>
265 <td>    Ctrl-Space
266 </td><td>Call auto-completion assistant
267 </td></tr>
268 <tr>
269 <td>    Alt-/
270 </td><td>Auto-complete. If multiple names match the already typed text, then you can cycle through them by hitting Alt-/ multiple times.
271 </td></tr>
272 <tr>
273 <td>    Ctrl-Shift-Space
274 </td><td>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.
275 </td></tr>
276 <tr>
277 <td>    Ctrl-/
278 </td><td>Comment in/out selected text or current line
279 </td></tr>
280 <tr>
281 <td>    Ctrl-Shift-F
282 </td><td>Automatic indent highlighted lines of code.
283 </td></tr>
284 <tr>
285 <td>    Ctrl-3
286 </td><td>Quick access: start typing and it shows all menus, editors, views, commands that match that substring
287 </td></tr>
288 <td>    Ctrl-Shift-L
289 </td><td>Show all key bindings, e.g,. for example to learn about more key shortcuts
290 </td></tr>
291 <tr>
292 <th colspan="2" style="background-color:#ffff99;"> Debugging
293 </th></tr>
294 <tr>
295 <td>    F6
296 </td><td> Step over (gdb's "next")
297 </td></tr>
298 <tr>
299 <td>    F5
300 </td><td> Step into (gdb's "step")
301 </td></tr>
302 <tr>
303 <td>    F7
304 </td><td> Step return (gdb's "finish")
305 </td></tr>
306 <tr>
307 <td>    F8
308 </td><td> Resume (gdb's "continue")
309 </td></tr>
310
311 <tr>
312 <th colspan="2" style="background-color:#ffff99;"> Running a program
313 </th></tr>
314 <tr>
315 <td>    Ctrl-B
316 </td><td> Build (call make)
317 </td></tr>
318 <tr>
319 <td> Ctrl-F11
320 </td><td> Run
321 </td></tr>
322 <tr>
323 <td> F11
324 </td><td> 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
325 </td></tr>
326 <tr>
327 <th colspan="2" style="background-color:#ffff99;"> Working with subversion (works both in file editors as well as the C/C++ project view)
328 </th></tr>
329 <tr>
330 <td> Ctrl-Alt-L
331 </td><td> Show diffs
332 </td></tr>
333 <tr>
334 <td> Ctrl-Alt-C
335 </td><td> Commit
336 </td></tr>
337 <tr>
338 <td> Ctrl-Alt-U
339 </td><td> Update from repository
340 </td></tr>
341 <tr>
342 <td> Ctrl-Alt-P
343 </td><td> Create a patch from local changes
344 </td></tr></table>
345
346 # Configuring Eclipse
347
348 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.
349
350
351 ## Showing line numbers and dealing with tabs
352
353 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".
354
355 '<img width="400px" src="http://www.dealii.org/images/wiki/Eclipse-line-numbers.png" align="center">'
356
357 <br>
358
359 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".
360
361
362 ## Enabling code folding
363
364 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:
365
366 '<img width="400px" src="http://www.dealii.org/images/wiki/Eclipse-folding-assistant.png" align="center" />'
367
368 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.
369
370 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.
371
372
373 ## Integrating Eclipse and Subversion
374
375 deal.II and many of its subprojects use [http://subversion.apache.org Subversion]([KDevelop]]) 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.
376
377 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.
378
379 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:
380
381 '<img width="400px" src="http://www.dealii.org/images/wiki/Eclipse-subversive-1.png" align="center" />'
382
383 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:
384
385   - 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".
386   - 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".
387
388 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.
389
390 ## Integrating Eclipse and Doxygen
391
392 [Doxygen](http://www.doxygen.org/) is one of the most important tools for generating high quality documentation for C++ software, and it is <em>the</em> 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:
393
394 '<img width="400px" src="http://www.dealii.org/images/wiki/Eclipse-doxygen.png" align="center" />'
395
396 Then select "Doxygen" as the "Documentation tool" in the bottom part of the panel on the right, as shown above.
397
398 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:
399
400 '<img width="800px" src="http://www.dealii.org/images/wiki/Eclipse-doxygen1.png" align="center" />'
401
402 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:
403
404 '<img width="800px" src="http://www.dealii.org/images/wiki/Eclipse-doxygen2.png" align="center" />'
405
406 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.
407
408 ## Code style issues
409
410 Eclipse can be configured in more ways than one can count. One issue is to configure 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. To this end:
411   - Highlight the deal.II project you have created above in the "Project Explorer" sub-window.
412   - Go to "Project > Properties" from the main menu, or right-click on the project and choose "Properties" in the context menu.
413   - Then go to expand the "C/C++ General" sub-tree by clicking on the down arrow next to it and select "Code style".
414   - 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.
415   - You can import the following style: [stylefile.xml](https://docs.google.com/open?id=0B1_zqLUYjm2ea1c0Y1VTdmJHNUU)
416   - Alternatively create a new one and choose the "GNU" style as the basis for this new style and follow the instructions below.
417
418 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):
419
420 '<img width="800px" src="http://www.dealii.org/images/wiki/Eclipse-code-indentation-3.png" align="left" />'
421
422 '<img width="800px" src="http://www.dealii.org/images/wiki/Eclipse-code-indentation-4.png" align="right" />'
423
424 '<img width="800px" src="http://www.dealii.org/images/wiki/Eclipse-code-indentation-5.png" align="left" />'
425
426 '<img width="800px" src="http://www.dealii.org/images/wiki/Eclipse-code-indentation-6.png" align="right" />'
427
428 '<img width="800px" src="http://www.dealii.org/images/wiki/Eclipse-code-indentation-7.png" align="left" />'
429
430 '<img width="800px" src="http://www.dealii.org/images/wiki/Eclipse-code-indentation-8.png" align="right" />'
431
432 '<img width="800px" src="http://www.dealii.org/images/wiki/Eclipse-code-indentation-9.png" align="left" />'
433
434 '<img width="800px" src="http://www.dealii.org/images/wiki/Eclipse-code-indentation-10.png" align="right" />'
435
436 '<img width="800px" src="http://www.dealii.org/images/wiki/Eclipse-code-indentation-11.png" align="left" />'
437
438 # Setting up Eclipse with Parallel Tools Platform (PTP)
439
440 Section currently under development. Please be patient.
441 ## What PTP is?
442
443 [PTP](http://www.eclipse.org/ptp/) is set of tool for developing, debugging and profiling MPI applications. Instructions for installation into existing Eclipse can be found [here](http://www.eclipse.org/ptp/downloads.php). Make sure you're trying to install correct PTP version for your Eclipse (7.0 for Kepler, 6.0 for Juno, 5.0 for Indigo). Most of installation issues are described in PTP release notes [v.7.0](http://wiki.eclipse.org/PTP/release_notes/7.0). 
444 ## Installing from package
445
446 This instructions have been tested under Ubuntu 12.04
447 If you were not able to install PTP into exesting  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](http://www.eclipse.org/downloads/).  "Eclipse for Parallel Application Developers Eclipse for Parallel Application Developers" is 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 same environmental variables as in terminal).
448 ## SDM - Scalable debug manager
449
450 Debugging parallel program 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](http://wiki.eclipse.org/PTP/release_notes/7.0#Install_optional_PTP_debugger_component) 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 ).
451 ## Setting up project with parallel run configuration
452
453 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.
454 ### Local projects (only with Eclipse Kepler with PTP 7.x)
455
456 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)
457 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.
458
459 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. Number of MPI processes can be increased in Resources tab.
460
461 ## Debugging parallel program
462
463 From drop-down list near bug icon select your debug configuration. You will be asked to confirm opening Parallel Debug perspective, click yes. The following view will appear: (PICTURE)
464
465 The main difference between default Eclipse debugger is "Parallel Debug" tab. The diamonds represents processes, green means that process is running, yellow - suspended, red -terminated. You can select one process by double click. 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 group of processes in "Parallel Debug" tab. 
466
467 More informations can be found in PTP help and tutorials.

In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.

Douglas Adams


Typeset in Trocchi and Trocchi Bold Sans Serif.