4. Getting up and running with QtCreator and QGIS

QtCreator is an 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 based applications (including mobile apps).

4.1. Installing QtCreator

Qt Creator is available on all major platforms and can be downloaded from https://www.qt.io/download (Go the open source route). The installation procedure depends on your platform.

If you are running a Unix-like platform, you can use the command line, eg on Debian:

sudo apt install qtcreator qtcreator-doc

After installing you should find it in your menu.

4.2. Setting up your project

We assume you have already got a local QGIS clone containing the source code, and have installed all needed build dependencies etc. There are detailed instructions for git access and dependency installation.

On our system we have checked out the code into $HOME/dev/cpp/QGIS and the rest of the article is written assuming that. You should update these paths as appropriate for your local system.

After 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/QGIS/CMakeLists.txt
../../_images/selectCMakeLists.png

QtCreator will parse the project and you will be prompted for a build location and options in the Configure Project dialog.

Since we want QGIS to have debugging capabilities we will only enable the debug entry and fill it with our build location:

  1. Check checkbox Select all kits enabling the Desktop entry

  2. Uncheck all but the checkbox Debug sub item

  3. Fill the path with the build directory. For our purpose, we create a specific build dir for QtCreator:

    $HOME/dev/cpp/QGIS/build-master-qtcreator

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

    ../../_images/configureProject.png

That's the basics of it. Press the Configure Project button and QtCreator will start scanning the source tree for autocompletion support and do some other housekeeping stuff in the background.

../../_images/configurationDone.png

We want to tweak a few things before we start to build.

4.3. Setting up your build environment

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

../../_images/leftPanel.png

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

../../_images/buildSettings.png

The dialog shows the Debug build configuration and allows you to edit settings under the CMake section. While the default configuration should be enough for a first pass, depending on your needs, you may want to enable more features such as:

  • WITH_3D = ON for 3D rendering

  • WITH_CUSTOM_WIDGETS = ON to add QGIS custom widgets for interface design

Press Apply Configuration Changes.

By default, Qt Creator uses all the CPU cores available to speed the build with maximum parallelization. To avoid that your computer freezes, you should specify a smaller number of cores. Under the Build Steps section:

  1. Press the Add build step ► menu and select Custom Process Step

  2. Fill the new form as follows:

    • Command: make

    • Arguments: -j4 to use 4 cores (setting depends on your device)

    • Working directory: %{buildDir}

../../_images/customProcess.png

Catatan

Also, if you want to reduce your build times, you can do it with ninja, an alternative to make with similar build options. You'd need to set it as the CMake generator:

  1. Open Tools ► Options ► Build & Run ► Kits

  2. Select the Desktop (default) kit entry, displaying its properties

  3. Press Change... next to CMake generator

You are now ready to build. Press the build Build button at the left bottom of the dialog (or Ctrl+B) to launch the project build! Qt Creator will begin compiling and this may take some time the first time, depending on your device.

At the end of the compilation, you can run QGIS by pressing the runInstall Run button.

The compilation of QGIS also generates binaries in the build directory. Hence you can execute QGIS from the command line using:

cd $HOME/dev/cpp/QGIS/build-master-qtcreator
./output/bin/qgis

Sometimes you may want to install QGIS as an executable, outside the build directory.

  1. Set the CMAKE_INSTALL_PREFIX to somewhere you have write access to (we use $HOME/apps). This would avoid overwriting an existing QGIS installs (by your package manager for example).

    ../../_images/customInstallPrefix.png

  2. Press Apply Configuration Changes to update the settings

  3. Press the build button

  4. When the build is complete, you'll find the qgis executable in the $HOME/apps/bin folder.

4.4. 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.

../../_images/image14.jpeg

Now launch QGIS under the debugger by clicking the runDebug Start Debugging in the bottom left of the window.