Posted by & filed under QGIS.

Getting up and running with QtCreator and QGIS
Firstly let me preface this article by saying that I am not a huge fan of IDEs – I’ve been using VIM for more than a decade and it’s a tough habit to break. That said, QtCreator has a lot going for it (including a special concession to VIM users) and it is a lot easier to use for debugging that crusty old gdb on the command line. So in the article below I am going to run through an optimal (from my point of view anyway) setup for using QtCreator to build, develop and debug QGIS with.
QtCreator is a newish IDE from the makers of the Qt library. With QtCreator you can build any C++ project, but it’s really optimised for people working on Qt(4) based applications (including mobile apps). Everything I describe below assumes you are running Ubuntu 11.04 ‘Natty’.

Installing QtCreator

This part is easy:

sudo apt-get install qtcreator qtcreator-doc

After installing you should find it in your gnome menu.

Setting up your project


I’m assuming you have already got a local Quantum-GIS clone containing the source code, and have installed all needed build dependencies etc. There are detailed in instructions on doing that here:
http://github.com/qgis/Quantum-GIS/blob/master/CODING

On my system I have checked out the code into $HOME/dev/cpp/Quantum-GIS and the rest of the article is written assuming that, you should update these paths as appropriate for your local system.
On launching QtCreator do:

File->Open File or Project

Then use the resulting file selection dialog to browse to and open this file:

$HOME/dev/cpp/Quantum-GIS/CMakeLists.txt

 

Open the top level CMakeLists.txt

Open the top level CMakeLists.txt

 

 

Next you will be prompted for a build location. I create a specific build dir for QtCreator to work in under:

$HOME/dev/cpp/Quantum-GIS/build-master-qtcreator

Its probably a good idea to create separate build directories for different branches if you can afford the disk space.

Build location

Build location

 

 

Next you will be asked if you have any CMake build options to pass to CMake. We will tell CMake that we want a debug build by adding this option:

-DCMAKE_BUILD_TYPE=Debug
CMake Parameters

CMake Parameters

 

 

Thats the basics of it. When you complete the Wizard, QtCreator will start scanning the source tree for autocompletion support and do some other housekeeping stuff in the background. We want to tweak a few things before we start to build though.

Setting up your build environment

Click on the ‘Projects’ icon on the left of the QtCreator window.

Project properties

Project properties

 

 

Select the build settings tab (normally active by default).

Build settings

Build settings

 

 

We now want to add a custom process step. Why? Because QGIS can currently only run from an install directory, not its build directory, so we need to ensure that it is installed whenever we build it. Under ‘Build Steps’, click on the ‘Add Build  Step’ combo button and choose ‘Custom Process Step’.

Add custom step

Add custom step

 

 

Now we set the following details:

Enable custom process step [yes]
Command: make
Working directory: $HOME/dev/cpp/Quantum-GIS/build-master-qtcreator
Command arguments: install
Creating a custom process step

Creating a custom process step

 

 

You are almost ready to build. Just one note: QtCreator will need write permissions on the install prefix. By default (which I am using here) QGIS is going to get installed to /usr/local. For my purposes on my development machine, I just gave myself write permissions to the /usr/local directory.

To start the build, click that big hammer icon on the bottom left of the window.

The build icon

The build icon

 

 

Setting your run environment

As mentioned above, we cannot run QGIS from directly in the build directly, so we need to create a custom run target to tell QtCreator to run QGIS from the install dir (in my case /usr/local/). To do that, return to the projects configuration screen.

Project properties

Project properties

Now select the ‘Run Settings’ tab

The run settings tab

The run settings tab

We need to update the default run settings from using the ‘qgis’ run configuration (shown below) to using a custom one.

Default executable which we want to override

Default executable which we want to override

Do do that, click the ‘Add v’ combo button next to the Run configuration combo and choose ‘Custom Executable’ from the top of the list.

Add a custom executable

Add a custom executable

Now in the properties area set the following details:

Executable: /usr/local/bin/qgis
Arguments :
Working directory:
$HOME
Run in terminal: [no]
Debugger: C++ [yes]
          Qml [no]

Then click the ‘Rename’ button and give your custom executable a meaning full name e.g. ‘Installed QGIS’

Custom executable properties

Custom executable properties

Running and debugging

Now you are ready to run and debug QGIS. To set a break point, simply open a source file and click in the left column.

Adding a breakpoint

Adding a breakpoint

Now launch QGIS under the debugger by clicking the icon with a bug on it in the bottom left of the window.

Run QGIS in debug mode

Run QGIS in debug mode

Conclusion

There are a few other handy tips and tricks you can do in QtCreator which I will try to cover in a future article. With the information presented above you should at least be on your way to having QGIS setup in QtCreator. Having an interactive debugger at your fingertips is a great way to learn to code in QGIS as it is easy to follow the logic flow from one class / to the next. It also makes it easy for casual developers to dive in and find a bug that is irritating them and either send us a comprehensive bug report or send use a fix :-).

  • http://www.bernawebdesign.ch/byteblog mbernasocchi

    Hi Tim, thanks for the post, today I even managed to crosscompile qgis to arm in QtCreator :) just an update, since the new commit from Martin, there is no need anymore to setup the custom executable, after running CMake, just hit run (or debug) and it asks you for the executable to run, choose yourbuilddir/output/bin/qgis and you are ready to rock.
    ciao Marco

    • http://linfiniti.com Tim Sutton

      Hi Marco

      Thanks for posting this comment. I look forward to posting notes on building for android with Qt Creator one of these days!

      Regards

      Tim

  • rduivenvoorde

    Hi Tim,
    I have a new machine and installed Oneiric on it
    So testing your instructions here… again, thanks :-)

    In the beginning you are pointing to the CODING docs, but I think (because you are referring to the dependecies), that you mean the INSTALL docs (I know where to find, but itś just for pointing new comers to have a good start)?

  • hidromatrix

    Hi Tim,

    Thanks for the excellent post. Would you have a Windows version of this walkthrough?

    Thanks in advance,

    Regards,

    Eduardo

    • http://linfiniti.com Tim Sutton

      Hi Eduardo

      Under Windows I usually use MSVC2008 for building and light tweaking. I tend to do any serious work under linux since life is a lot easier there for me. It should be possible to use QtCreator under windows too, and if I ever need to do so I will be sure to blog about the process. Right now unfortunately I don’t have the time to do so. It may be worth enquiring on the developer list to see if anyone else has done so.

      Regards

      Tim

  • bholland

    I think it would be very nice to edit this entry to be more in line with the README found in the application. In the README it is specified that to change the prefix so that it isn’t built on /usr/local but to say, $HOME/apps. The way to do this in QT Creator is to pass 2 arguments to cmake:
    -DCMAKE_BUILD_TYPE=Debug
    -DCMAKE_INSTALL_PREFIX=$HOME/apps

    This makes this post more in line with the README.

  • bholland

    Oh BTW, ubuntu 13.04 64-bit doesn’t link python shared libraries correctly. Theres should be an addendum to the build step for cmake. The correct option to add to cmake to pick up python is:

    -DPYTHON_LIBRARY=/usr/lib/x86_64-linux-gnu/libpython2.7.so

    Otherwise you have a ton of build errors like

    undefined reference to py_initialize