[GSoC] Class and Test Templates in KDevelop

 

I have generalized the “Create Class” dialog, so that it starts with a template selection page that is similar to what you see when starting a new project. It offers you a selection of templates of different types (currently only Class and Test) and programming languages. Selecting a templates leads to further assistant pages, which are chosen dynamically depending on the selected template’s type.

The first page of the “Create from Template” dialog

I have added wrapper classes for template rendering with Grantlee (KDevelop::TemplateRenderer) and template archives (KDevelop::SourceFileTemplate), so the assistant only deals with those to keep the code clean and readable. Both class and tests use the same format of template archives (described here), only with a some different variables.

As you can see from the screenshot, there’s already quite a few available templates to choose from. Considering a template only has to be written once, every project could have one or more preferred templates for new code. Existing ones can always be re-used, or maybe just tweaked slightly, so a little work can improve coding style and consistency.

 

 

[GSoC] Templates in KDevelop – Week 5

My last report (here) was full of pictures, but since then I’ve spent more time polishing the functionality, behind-the-scene improvements, and fixing bugs. However, the mid-term evaluation is approaching, so I think let everybody know what’s the state of things. I’m happy with my progress, my schedule was a bit vague, but I think I’m ahead of it. So far I’m still enjoying it, and I bought a more comfortable chair, so I have little problems with working long hours.

I split out some functionality to make code more modular, which also allowed me to write unit tests for much of the newly added classes. The main parts of the code (TemplateRenderer, TemplateClassGenerator and TemplatesModel) are covered with test cases.

Class Templates

My main focus was still on templates for creating new classes. I slowly decided on the variables passed to templates. They are also documented, and I think I can start writing more templates about now. The C++ plugin adds some variables of its own, such as namespaces,

Since KDevelop’s Declarations must always point to a location in a source file, they cannot be created directly, I had to add my own classes for describing code before it is generated. This way, data members of a class can be declared. These code description classes are very simple, with only a couple of members, and are written so that Grantlee templates have access to all their properties.

The state of template class generation is such that it covers all functionality of the existing “Create Class” dialog. I have already written a basic C++ template that produces the same output. Of course, it is possible to create different classes, such as ones with private pointers, QObject’s macros, or in different languages.

Writing the Class Templates

As I said, I already wrote a template for a basic C++ class, as well as one with a d-pointer. Since I figured a lot of the code would be shared between templates for the same language, I added some basic templates that can be included. These are for method declarations, argument lists, namespaces, include guards, and some other small conveniences. There is also a library of custom template filters in kdevplatform. The end result is that the templates themselves can be relatively small. I even reduces the amount of whitespace in the rendered output, so that templates can be more readable while the generated classes are compact enough.

However, I don’t think it’s practical to store templates and filters for all possible languages in kdevplatform. So I intend to add a way for templates to specify dependencies on language plugin. Of course, they could still be written from scratch, or simply ship with the needed includes. It is merely a convenience.

The plan is to have language plugins provide some of their own templates and filters, but so far they are only for C++.

Templates, Templates Everywhere

Of course, KDevelop has other utilities for code generation, and I figured templates would be useful there as well. I started with inserting API documentation. The previous implementation manually constructed a Doxygen C++ style comment. I replaced that with a renderer template, which now supports C++, Php and Python.

Pressing Alt-Shitf-D on a declaration of a C++ functions results in this

API documentation with Doxygen for C++

While doing the same thing on a Python function produces this

API documentation with reST for Python

Not only is it formatted in reST, the most common format for Python documentation, but it also is positioned below the declaration, as a true Python docstring. Obviously, we still need to convert __kdevpythondocumentation_builtin type names to python types, but stripping a prefix can be done within a template thanks to Grantlee’s built-in filters.

Becoming a KDeveloper

So, I’ve just been accepted into this year’s Summer of Code program. I’ll be working on KDevelop, introducing a system for using and sharing code templates. This includes both project templates (integrating KNewStuff into KAppTemplate) and more specialized templates (for code files,  classes, tests, make and cmake files, etc). The full proposal is online at http://www.google-melange.com/gsoc/proposal/review/google/gsoc2012/noughmad/37002.

However, all this is still in the future. I’ve already been doing some work on KDevelop, and so far I’ve enjoyed it very much. Not only do I use it every day, its plugin architecture makes it easy to add small pieces of functionality. Note that because of school getting harder every year, I have little free time and my progress is a bit slow. But anyway, I’ll show you what I wrote the past few moths.

Unit tests

KDevelop currently has no support for unit testing. However, both KDevelop and KDevPlatform have loads of them, so a good system for running tests and reporting their results would find a good use. So I introduced some new interfaces for unit tests, including finding and running them. A toolview was adapted from the old and unmaintained Veritas library, however I took steps to better separate the interfaces and their implementations. Currently supported are tests declared with CMake and those using the PHPUnit framework.

A toolview for listing unit test suites and their test cases

Apart from simply listing tests, the relevant declarations are also extracted and a “show source” action is available. Support for running unit tests and reporting results is also functional, however I have trouble deciding which icons to use. There is a difference between a failed test case and an error, and also between an individual testcase and suite results. As a short-term solution I implemented a mess of different icons.

The toolview showing results of a test run

Finding tests declared in CMake files works reliable, whether they use add_test() directly or some wrapper macro (like kde4_add_test()). Unfortunately, this is not true for php tests cases. The problem with PHPUnit is that a test case must inherit from a certain class, but  doesn’t have to include any special file, so the parser find the right declaration by itself. I managed to fix it by modifying the parser, so that most test cases are found, but unfortunately still not all.

Additionally, when running the test cases, their output is displayed in a separate toolview. For test cases using QtTest or PHPUnit, the output is highlighted appropriately (green for success, red for failure). For Qt-based tests, clicking a line in the output also takes you to the declaration in the code.

An output from a test using the QtTest framework

If you wish to test this, the code is in the “unittest” branches of kdevplatform, kdevelop and kdev-php. Any input is appreciated, especially regarding the presentation to the user.

Code checking

Another valuable resource for KDE developers is the Krazy code checker. Seeing how easy it is to create KDevelop plugins, I wrote another one to run Krazy and report back the results. Any issues found are inserted into the declaration-use chain, so they are visible in the Problems toolview, as well as in the code itself.

An issue found by Krazy displayed in the Problems view and in the code

The code is still in my personal scratch repository at http://quickgit.kde.org/index.php?p=scratch%2Fmihac%2Fkdev-krazy.git&a=summary

When all else fails

I also implemented a different kind of code checking: by humiliation. If you stumple upon a horrible piece of code, either written by you or inherited, you can earn a feeling of superiority by sending it over to The Daily WTF.

A context menu entry for submitting an offending code snippet to The Daily WTF

I haven’t yet submitted any code with it, but I tested the plugin with Alex, the site’s maintainer, and he says it works. So watch out, if you write bad code, even if you fool all the unit tests and code checking tools, someone can still expose you.

KDevelop vs VisualStudio for Qt/C++

Since I’m writing a multiplayer card game system in Qt, I’d like to make sure for it to be as cross-platform as possible. That’s why I signed up for MSDN Academic Alliance via the university, which gave me free access to Windows and Visual Studio.

This gives me an opportunity to compare VS against my current favourite, KDevelop. It is fitting that both projects are currently in a beta stage and both future releases promise great improvements. I’ll try to be objective, but my only experience is with a CMake-Qt C++ project, which certainly isn’t VS’s focus

In ease of installation, KDevelop wins hands down. Even not using the linux standard {one-line|three-click} package install, compiling KDevelop from source takes less time and effort than downloading and installing VS.