28 July, 2011

Autotools Project Manager, part 1: Understanding QtCreator's Project Explorer

It has already been more than one year since Peter Penz created a plugin for autotools support to be used with Qt Creator. In the meantime, Qt Creator developers have been busy, and having fun, rewriting several parts of the code, which, on the one hand, leads to nicer, improved interfaces, but on the other hand, to API breaks. So, it was time to "update" (redo) his work, and this is what I am currently working on.

For a trainee with a year’s experience, this is a more than challenging task: no experience developing for Qt Creator or with plugins, nor much experience with autotools, no documentation at all... In the beginning, I did not know how to start, nor if I could actually get something done at all, but then, with the help of the wisdom and patience of Peter Penz, David King and some of the Qt Creator guys, Tobias Hunger and Daniel Molkentin, things started to develop.

There is no documentation on how to develop a plugin for Qt Creator, so I had to spend a lot of time reading Qt Creator's code, in order to understand which bits I would need and how they were related. As I already said, this was very time consuming, so I have decided to write a series of posts, of which this is the first, to share what I learnt with you, and maybe save you some time in the future. As always, this is not meant to be a guide or tutorial; this is just what I did and how I understood it. I would be happy if this helps you deal with the huge monster that is Qt Creator, or even if I get some feedback on things which might be wrong :)).

Understanding some basics:
Qt Creator is a plugin loader and all its functionality is implemented in plugins. A very basic Qt Creator plugin has three different parts:
  1. .pro file, which is the project file.
  2. .pluginspec.in file, that provides some information about the plugin.
  3. projectplugin files, with the implementation of the ExtensionSystem::IPlugin interface in a class.
Also, to give support for a new project type — in our case, the autotools project — we need to implement some interfaces in the ProjectExplorer plugin, which is what I am going to focus on in this post.

The ProjectExplorer plugin
The ProjectExplorer plugin is a set of classes and interfaces that make up the project management system in Qt Creator. Its architecture is detailed in the chart, and explained in the following lines:

The Project (ProjectExplorer::Project) is the whole project itself, and it is always associated with a MIME type (specified in an .mimetypes.xml file), which defines the kind of file the project will be indentifed by, when the project is opened in Qt Creator.

The ProjectExplorer::Project class loads the project and embeds it into the QtCreator project tree. Every project supports one or more Targets (ProjectExplorer::Target), which are the target environments for which the developer wants to build the project (desktop, Symbian devices and
MeeGo, among others).

A Target can have several BuildConfigurations (ProjectExplorer::BuildConfiguration), DeployConfigurations (ProjectExplorer::DeployConfiguration) and RunConfigurations (ProjectExplorer::RunConfigurations).

A BuildConfiguration (for example, release or debug) represents all that is needed to build the project for the target. Each BuildConfiguration currently has two BuildStepLists (ProjectExplorer::BuildStepList), which are a set of instructions to run. The first list is used to build, and the second one to clean up. The BuildStepLists contain BuildSteps (ProjectExplorer::BuildStep), which are the steps that need to be executed ("make", "make clean", etc.).

A DeployConfiguration contains a BuildStepList, and is used to deploy the aforementioned BuildConfiguration output into the right place for later execution by the RunConfiguration.

A RunConfiguration defines what needs to be run: usually the program that was built before. It could also be some set of unit tests, a script, some existing application which is used to test a library that was just built, etc.

You can also get an overview of what a generic plugin should implement by looking at the genericprojectmanager plugin example in the qt-creator/src/plugins/genericprojectmanager directory.

Have fun!


    1. thanks!
      this was very interesting, nice to finally get some kind of documentation for doing this.

    2. For the autotools parsing you might want to look in the anjuta source code which features a yacc/bison-based Makefile.am and configure.ac parser. (plugins/am-project/*)

    3. Thanks from me too. QtCreator and Qt are really amazing tools for developers.

    4. Project planning: As the name suggests, this is the initial planning for your project. It doesn't need to be as in depth as waterfall project management plans, but should still contain a vision statement and a roadmap of where you plan to go.

      project contract management