KDevelop
KDevelop is a modern integrated development environment (IDE) for C++ (and other languages) that is part of the KDE desktop environment project. As such it runs on Linux (even if you run one of the other desktops, such as GNOME) but it is also available for most other variants of Unix as well as on Windows.
KDevelop offers all modern amenities of IDEs. For a large project like deal.II
and applications built on it, the most important feature is that KDevelop
understands C++: it parses the entire source base and remembers which classes
have which member functions. For example, when you then type
Vector v(10);
double n = v.l2
it will have remembered that the v is a variable of type
Vector and offer you to complete l2 as
l2_norm since this is the only member function of the
Vector class that starts like this. Instead of continuing to type
you just hit enter to get the full word; this saves typing, avoids typos, and
doesn't require you to remember all those ridiculously long names in deal.II. This, by the way, would also have worked if the vector v had been declared in an entirely different file, maybe as a member variable of the surrounding class in some header file.
As a second example, assume you have code like this:
double foo ()
{
double var = my_func();
return var ** var;
}
double bar ()
{
double var = my_func();
return var ** var * var;
}
If you hover the mouse over the symbol var in function bar you get the option to see all uses of this symbol. Clicking on it will only show you the uses of this variable in function bar because KDevelop understands that the variable var in function foo has nothing to do with it. Similarly, right clicking on the variable name allows you to rename the variable; doing so will only touch the variable in bar but not the one with the same name in foo.
There are other things KDevelop does well. Obviously, it highlights the source code in different colors; it has a customizable indenter; it has an integrated interface to the GNU debugger gdb; it can show you the documentation for a function if you hover the mouse over a use of this function; and many other neat things, some of which we will discuss below.
The following description was written for KDevelop 4.2.x. I have found that KDevelop 4.0 and 4.1 were too buggy and crashed too often for a project the size of deal.II to be usable.
Note: The KDevelop manual has much much more information on using KDevelop (the first version of the manual was generated by copying this page; I have written many more pages for the manual, however).
KDevelop has the concept of sessions and projects. A session contains all projects that have something to do with each other. For example, assume you are developing an application based on deal.II, then you would have a session in KDevelop that has two projects: both deal.II itself as well as your own application. If you also happen to be a gdb developer, then you would have a second session that contains gdb as a project. You could in principle have just one session for all of this, but you probably don't want gdb functions to be offered to you when you write a deal.II project.
Another use for sessions is if you work both on the current development version of deal.II and/or your own project, as well as on a branch: in that case, you don't want KDevelop to confuse classes that belong to mainline and the branch, so you'd have two sessions, with the same set of projects but from different directories.
Let's say you want to develop with deal.II. Then you would first create a new session via the "Session" menu at the top left. Next, go to the "Project" menu to create deal.II as a project inside this session. To to this, follow these steps:
- Go to "Projects > Fetch project" to import a project
- Assuming you wanted to work with the current development sources of deal.II and don't already have a version checked out:
- In the dialog box, under "Select the source", choose to use "Subversion"
- Choose working directory
- Choose URL for source: http://www.dealii.org/svn/dealii/trunk/deal.II
- Hit "Get". This takes quite a long while; depending on the speed of your connection this can easily be 10 or more minutes. Unfortunately, in KDevelop 4.2.x the progress bar does not actually show anything, but you can track progress by periodically looking at the output of the command line command
du -sk /path/to/KDevelop/projectto see how much data has already been downloaded. (Note 1: The problem with the progress bar has been reported as KDevelop bug 256832. Note 2: In this process, I also get the error message "You need to specify a valid location for the project" which can be safely ignored.)
- It asks you to select a KDevelop project file in this directory. Since you probably don't have one yet, simply hit "Next"
- Hit "Next" again
- Choose the custom makefile project manager
- KDevelop will then start to parse the entire project. Again, it will take quite a while to go through all files and index classes etc. At the bottom right of the main window, there is a progress bar on the bottom right that shows how long this process has come along. (If you have several processor cores, you can accelerate this process by going to the "Settings > Configure KDevelop" menu item, then selecting "Background parser" on the left, and increasing the number of threads for background parsing on the right.)
If you already have deal.II checked out from the repository or if you want to use a release version of deal.II that you have already unpacked in a directory, go through the same list as above but in step 2 choose "Do not obtain" under "Select the source" and instead just provide the path to the directory on your hard drive that you want to use.
The next thing you want to do is set up other projects using deal.II in the same session. For example, if you want to work on one of the tutorial programs (or another program that you have under the general deal.II directory tree, you would follow the same list of steps again but instead of fetching from a subversion repository you would select "Do not obtain" and just point KDevelop at the directory in which your project resides. If your project is in a directory elsewhere in your file system or you want to check it out from a repository, you should be able to follow the steps above as well.
If you have multiple applications or libraries, simply repeat the steps to add more and more projects to your session.
'
In order to work with projects, KDevelop has the concept of "tools". A tool provides a particular view of the source, or an action that can be taken with it. Tools are represented by buttons around the perimeter of your window (in vertical text along the left and right margins, or horizontally along the bottom margin). If you click on them, they expand to a subwindow within the main window; if you click on the tool button again, the subwindow disappears again. (Note: To make a subwindow disappear, you can also click at the "x" at the top right of the subwindow; however, at least with KDevelop 4.2.x, this also removes the button representing the tool from the perimeter, which was your way of getting the subwindow back. See below for how to get the button back onto the perimeter in the same way as getting any tool's button there. This behavior has been reported as bug 270018). The picture on the right shows my own selection of tools, aligned on the left and right margins; in the picture, I have the "Classes" tool open on the left and the "Snippets" tool on the right, along with an editor for a source file in the middle. In practice, I find myself only having the editor and maybe the "Classes" or "Code Browser" tool open at the left; I only temporarily use the tools on the right, leaving me sufficient space for the editor.
When you run KDevelop the first time, you should already have the "Projects" tool button. Click on it: it will open a subwindow that shows the projects you have added to the session at the bottom, and a file system view of the directories of your projects at the top.
There are many other tools you can use with KDevelop, not all of which are initially present as buttons on the perimeter. To add some, go to the "Windows
Add tool view" menu entry. Here are a few useful ones I have added:
- Classes: A complete list of all classes that are defined in one of the projects or your session with all of their member functions and variables. Clicking on any of the members opens a source editor window at the location of the item you clicked on.
- Documents: Lists some of the more recently visited files, by kind (e.g. source files, patch files, plain text documents).
-
Code Browser: Depending on your cursor position in a file, this tool shows things that are related. For example, if you are on an
#includeline, it shows information about the file you are including such as what classes are declared in that file; if you are on an empty line at file scope, it shows the classes and functions declared and defined in the current file (all as links: clicking on them brings you to the point in the file where the declaration or definition actually is); if you are in a function definition, it shows where the declaration is and offers a list of places where the function is used. - File system: Shows you a tree view of the file system.
- Documentation: Allows you to search for man pages and other help documents.
-
Snippets: This provides sequences of text that one uses over an over and doesn't want to write every time. For example, code like
for (typename Triangulation<dim>::active_cell_iterator cell = triangulation.begin_active(); cell != triangulation.end(); ++cell)would make for a good snippet. -
Konsole: Opens a command line window inside KDevelop's main window, for the occasional command you may want to enter (e.g. to run
./configure).
Since for me vertical screen space is the most important, I have arranged my tool views at the left and right margin of the window. You can move a tool view by clicking on its symbol with the right mouse button.
KDevelop doesn't know about autoconf, so you will have to run
./configure by hand on a command line. If you have the
Konsole tool as described above, you can even run
./configure from a command line inside KDevelop.
The next steps are to teach KDevelop about targets in your Makefiles. There are two ways to do that: selecting individual Makefile targets, and choosing a set of targets you may want to build frequently. For both approaches, open the "Projects" tool by clicking on the "Projects" button on the perimeter of KDevelop's main window (if you don't have this button see above how to add a tool's button there). The "Projects" tool window has two parts: the top half -- titled "Projects" -- lists all of your projects and let's you expand the underlying directory trees. The bottom half -- titled "Project Selection" -- lists a subset of those projects that will be built if you choose the menu item "Project > Build selection" or hit F8; we'll come back to this part below.
In the top part of the project view, expand the sub-tree for one project, let's say the deal.II project. This will give you icons for (i) directories under this project, (ii) files in the top-level directory for this project, (iii) Makefile targets KDevelop can identify. These categories are shown in the picture at right.
'
To build any of the targets listed there, click on it with the right mouse button and select "Build". For example, doing this with the "clean" target will simply execute "make clean". You can see this happening in the subwindow titled "Build" that opens up, showing the command and the output. (This window corresponds to the "Build" tool, so you can close and later re-open the window using the "Build" tool button on the perimeter of the main window. It is shown at the bottom right of the picture on the right.)
Right-clicking on individual Makefile targets every time you want to build something will quickly get old. Rather, we'd like to have individual targets for one or more of the projects in the session that we can repeatedly build without much mouse work. This is where the concept of "Build target selections" comes in: it is a collection of Makefile targets that are built one-after-the-other whenever you hit the "Build selection" button in the button list at the top, select the "Project > Build selection" menu item, or hit the F8 function key.
The list of selected Makefile targets is shown in the bottom half of the "Projects" tool view. By default, the selection contains all projects, but you can change that. For example, if your list of projects contains deal.II and two of the tutorial programs, but you're currently only working on step-A, then you may want to remove step-B from the selection by highlighting it in the selection and hitting the red "-" button. Furthermore, you probably want to make sure that the deal.II project is built before the step-A project by moving entries in the selection up and down using the buttons to the right of the list. You can also get a particular Makefile target into the selection by right-clicking onto it and selecting "Add to buildset", or just highlighting it and hitting the green "+" button just above the list of selected targets.
In the specific case of deal.II, Kdevelop's default of just calling "make" will not work: it will simply produce a screen with possible "make" targets. Consequently, you will want to remove the default "deal.II" project from the selection and instead add individual targets to the selection. If you're a deal.II developer, a useful target to add would be "all".
KDevelop allows you to configure what to do whenever you build the selection. To this end, use the menu item "Project > Open configuration". There, you can for example select the number of simultaneous jobs "make" should execute -- if your computer has, say, 8 processor cores, then entering 8 in this field would be a useful choice. I don't enter anything as the "Default make target" since this would be a Makefile target used for all targets in the selection.
If the compiler encounters an error message, simply click on the line with the error message and the editor will jump to the line (and if available column) where the error was reported. Depending on the error message, KDevelop may also offer you several possible actions to fix the error, for example by declaring a previously undeclared variable if an unknown symbol was found.
Once you have built a program, you will want to run it. To do this, you will want to configure "Launches" for your projects. A "Launch" consists of the name of an executable, a set of command line parameters, and an execution environment (such as "run this program in a shell", or "run this program in the debugger").
'
To set this up go to menu item "Run > Configure launches", highlight the project you want to add a launch for, and click on the red "+" button. Then enter the name of the executable, and the path where you want to run the program. If running the executable depends on building the executable and/or other libraries first, then you may want to add them to the list at the bottom: select "Build" from the dropdown menu, then hit the folder symbol to the right of the textbox and select whatever target you want to have built. In the example to the right, I have selected the target "all" from project "1.deal.II" and "step-32" from project "1.step-32" to make sure both the library and the application program have been compiled and are up to date before the program is actually executed. While you're there, you may as well also configure a debug launch by clicking on the "Debug" symbol and adding the name of the debugger program; if this is the system's default debugger (e.g. gdb on linux), then you don't need to do this step.
'
You can now try to run the program: Select "Run > Execute Launch" from the menu (or hit Shift-F9) and your program should run in a separate subwindow of KDevelop. The picture at the right shows the result: The new "Run" tool subwindow at the bottom shows the output of the program that is being run, in this case of the step-32 tutorial program.
Note: If you have configured multiple launches, you can choose which one should run when you hit Shift-F9 by going to "Run > Current Launch Configuration". Unfortunately, by default, all launches are named "New Native Application" without an obvious possibility of renaming them, making it difficult to distinguish them when selecting the current launch configuration (see KDevelop bug 272300). There is a way to edit the name of a configuration, however: in the dialog box you get when you select {{{Run > Current Launch Configuration}}}, double-click on the name of the configuration in the tree view on the left, which will allow you to edit the configuration's name.
Once you have a launch configured, you can also run it in a debugger: Select the menu item "Run > Debug Launch", or hit F9. If you are familiar with gdb, the effect is the same as starting gdb with the executable specified in the launch configuration and then saying "run". This means that if the program calls abort() somewhere (e.g. when you run onto a failing assertion) or if there is a segmentation fault, then the debugger will stop. On the other hand, if the program runs to the end (with or without doing the right thing) then the debugger will not stop by itself before the program is finished. In the latter case, you will want to set a breakpoint on all those lines of your code base where you want the debugger to stop before you run the debug launch. You can do that by moving the cursor on such a line and selecting the menu item "Run > Toggle breakpoint", or right-clicking on a line and selecting "Toggle breakpoint" from the context menu.
'
Running a program in the debugger will put KDevelop in a different mode: it will replace all the "Tool" buttons on the perimeter of the main window by ones that are appropriate for debugging, rather than for editing. You can see which of the mode you are in by looking at the top right of the window: there are tabs named "Review", "Debug", and "Code"; clicking on them allows you to switch back and forth between the three modes; each mode has a set of tool views of its own, which you can configure in the same way as we configured the "Code" tools above.
Once the debugger stops (at a breakpoint, or a point where abort() is called) you can inspect a variety of information about your program. For example, in the image at the right, we have selected the "Frame stack" tool at the bottom (roughly equivalent to gdb's "backtrace" and "info threads" commands) that shows the various threads that are currently running in your program at the left (here a total of 8) and how execution got to the current stopping point at the right (here: main() called run(); the list would be longer had we stopped in a function called by run() itself). On the left, we can inspect local variables including the current object (the object pointed to by the this variable).
From here, there are various possibilities you can do: You can execute the current line (F10, gdb's "next" command), step into the functions (F11, gdb's "step" command), or run to the end of the function (F12, gdb's "finish" command). At every stage, KDevelop updates the variables shown at the left to their current values. You can also hover the mouse over a symbol in your code, e.g. a variable; KDevelop will then show the current value of that symbol and offer to stop the program during execution the next time this variable's value changes. If you know gdb, you can also click on the "GDB" tool button at the bottom and have the possibility to enter gdb commands, for example in order to change the value of a variable (for which I have not yet found another way).
There are a number of useful things one can configure in and around KDevelop's builtin editor. Of more universal use is to switch on line numbering using the menu entry "Editor > View > Show line numbers", making it easier to match compiler error messages or debug messages with locations in the code. In the same submenu you will probably also want to switch on the "Icon border" -- a column to the left of your code in which KDevelop will show icons such as whether there is a breakpoint on the current line.
KDevelop has an almost boundless list of keyboard shortcuts (some of them are listed below) that can be changed to your taste through the menu "Settings > Shortcuts". At the top of the dialog you can enter a searchword and it only shows those commands that match; you can then edit which key combination is bound to this command. Two that I have found to be very useful to change are to set "Align" to the "tab" key (I don't usually enter tabs by hand and rather prefer if me editor chooses the layout of code for me; with the changed shortcut, hitting "tab" makes KDevelop indent/outdent/align the code for me). The second one was putting "Toggle Breakpoint" on "Ctrl-B" since this is quite a frequent operation.
On a more personal level, many of us like code formatted in a particular way. This, too, can be customized. To this end, go to the "Settings > Customize KDevelop" menu item, then click on "Source Formatter" on the left. You can choose one of the predefined indentation styles, or define your own one by adding a new style and then editing it. There is currently no way to exactly re-create the style in which deal.II sources have been indented in the past, but you can come close by using the settings for a new style that are shown in the two pictures below.
'
'
Note: With KDevelop 4.2.2, you can create a new style for a particular mimetype (e.g. for C++ header files) but this style does not show up among the list of possible styles for other mimetypes (e.g. for C++ source files) although it would of course be useful to use the same style for both kinds of files. You will therefore have to define the style twice, once for header and once for source files. This has been reported as KDevelop bug 272335.
I found the following key combinations useful, beyond the usual ones to open or save files, etc:
| Editing | |
|---|---|
| Jumping around in code | |
| Ctrl-Alt-O | Quick open file: enter part of a filename and select among all the files in the current session's projects' directory trees that match the string; the file will then be opened |
| Ctrl-Alt-C | Quick open class: enter part of a class name and select among all class names that match; the cursor will then jump to the class declaration |
| Ctrl-Alt-M | Quick open function: enter part of a (member) function name and select among all names that match; note that the list shows both declarations and definitions and the cursor will then jump to the selected item |
| Ctrl-Alt-Q | Universal quick open: type anything (file name, class name, function name) and get a list of anything that matches to select from |
| Ctrl-Alt-N | Outline: Provide a list of all things that are happening in this file, e.g. class declarations and function definitions |
| Ctrl-, | Jump to definition of a function if the cursor is currently on a function declaration |
| Ctrl-. | Jump to declaration of a function or variable if the cursor is currently in a function definition |
| Ctrl-Alt-PageDown | Jump to next function |
| Ctrl-Alt-PageUp | Jump to previous function |
| Ctrl-G | Goto line |
| Searching and replacing | |
| Ctrl-F | Find |
| F3 | Find next |
| Ctrl-R | Replace |
| Ctrl-Alt-F | Find-Replace in multiple files |
| Other things | |
| Ctrl-_ | Collapse one level: remove this block from view, for example if you want to focus on the bigger picture within a function |
| Ctrl-+ | Expand one level: undo the collapsing |
| Ctrl-D | Comment out selected text or current line |
| Ctrl-Shift-D | Comment in selected text or current line |
| Alt-Shift-D | Document the current function: move the cursor on a function or class declaration; hitting this key will already pre-populate a doxygen-style comment listing all parameters, return values, etc. |
| Ctrl-T | Transpose the current and the previous character |
| Ctrl-K | Delete the current line (not just emacs' "delete from here to the end of the line") |
| Debugging | |
| F10 | Step over (gdb's "next") |
| F11 | Step into (gdb's "step") |
| F12 | Step out of (gdb's "finish") |
| Running a program | |
| F8 | Build (call make) |
| Shift-F9 | Run |
| F9 | Run program in the debugger; you may want to set breakpoints beforehand, for example by right-clicking with the mouse on a particular line in the source code |
If you are working with larger projects, chances are that the source code is managed by a version control system such as subversion. If the directory in which a project is located is under version control, KDevelop will automatically notice. (In other words: It is not necessary that you tell KDevelop to check out a copy itself when setting up your project; it is ok to point KDevelop at a directory into which you have previously checked out a copy from the repository.)
If you have such a directory under version control, open the "Projects" tool view. There are then a number of things you can do:
-
If your directory has become outdated, you can update it from the repository: Click on the project name with the right mouse button, go to the menu "Subversion" and select "Update". This will bring all files that belong to this project up to date with respect to the repository.
-
If you want to restrict this action to individual subdirectories or files, then expand the tree view of this project to the level you want and right click on a subdirectory or file name, then do the same as above.
'
-
If you've edited one or more files, expand the view of this project to the directory in which these files are located and right click on the directory. This gives you a menu item "Subversion" that offers you different choices. Choose "Compare to base" to see the differences between the version you have edited and the version in the repository you had previously checked out. The resulting view will show the "diffs" for all files in this directory.
-
If you only edited a single file, you can also get the "Subversion" menu by simply right clicking on the corresponding file name in the project view. Even simpler, just right clicking into the editor window will also give you this menu option.
-
If you want to check one or more edited files in, right click either on an individual file, subdirectory, or whole project and select "Subversion > Commit". This will get you into "Review" mode, the third mode besides "Code" and "Debug" as you can see in the top right corner of the KDevelop main window. The picture on the right shows you how this looks. In review mode, the top part shows you diffs for the entire subdirectory/project and each individual changed file with changes highlighted (see the various tabs on this part of the window). By default, all changed files are in the changeset you are about to commit, but you can unselect some of the files if their modifications are unrelated to what you want to commit. For example, in the example on the right I have unselected
step-32.ccandstep-32.prmbecause the changes in these files have nothing to do with the other ones in this project and I don't yet want to check them in. After reviewing the changes you can enter a commit message into the text box and hit "Commit" on the right to send things off. -
As with seeing differences, if you want to check in a single file you can also just right click into the editor window to get the "Subversion > Commit" menu item.
'
Sometimes, one wants to debug a program that's already running. One scenario for this is debugging parallel programs using MPI, see the section on this in the [Questions and Answers]]([Deal.II). To do this, go to the menu entry "Run > Attach to Process", which will open a window like the one on the right. You will want to select the program that matches your currently open project in KDevelop -- in my case that would be the step-32 tutorial program.
This list of programs can be confusing because it is often long as in the case shown here. You can make your life a bit easier by going to the dropdown box at the top right of the window. The default value is "User processes", i.e. all programs that are run by any of the users currently logged into this machine (if this is your desktop or laptop, you're probably the only such user); it doesn't include processes run by the root user. You can limit the list by either choosing "Own processes", removing all the programs run by other users. Or better even: Select "Programs only", which removes a lot of processes that are formally running under your name but that you don't usually interact with, such as the window manager, background tasks and so on that are unlikely candidates for debugging.
Once you have selected a process, attaching to it will get you into KDevelop's debug mode, open all the usual debugger tool views and stop the program at the position where it happened to be when you attached to it. You may then want to set breakpoints, viewpoints, or whatever else is necessary and continue program execution by going to the menu item "Run > Continue".