Using CMake to Build Qt Projects

Written by: Johan Thelin

Qt comes with the QMake tool for handling cross platform building issues. However, there are other build systems available such as autotools, SCons and CMake. These tools meet different criterias, for example external dependencies.

When the KDE project shifted from Qt 3 to Qt 4 the project changed build tool from autotools to CMake. This has given CMake a special position in the Qt world &emdash; both from the number of users point and from a feature support and quality point. Seen from a workflow point of view, Qt Creator supports CMake since version 1.1 (1.3 if you want to use a Microsoft toolchain).

A Basic Example

In this article we will focus on CMake itself, and how to use it in conjunction with Qt. To do this, let's start with an overview of a simple, but typical CMake-based project. As you can tell from the listing below, the project consists of some source files and a text file.

$ ls
CMakeLists.txt
hellowindow.cpp
hellowindow.h
main.cpp

Basically, the CMakeLists.txt file replaces the projectfile used by QMake. To build the project, create a build directory and run cmake and then make from there. The reason for creating a build directory is that CMake has been built with out-of-source building in mind from the very start. It is possible to configure QMake to place intermediate files outside the source, but it requires extra steps. With CMake, it is the default.

$ mkdir build
$ cd build
$ cmake .. && make


CMake building a basic project.

The argument given to CMake refers to the directory where the CMakeLists.txt file resides. This file controls the whole build process. In order to fully understand it, it is important to recognize how the build process looks. The figure below shows how the user files: sources, headers, forms and resource files are processed by the various Qt code generators before joining the standard C++ compilation flow. Since QMake was designed to handle this flow, it hides all the details of this flow.


The Qt build system.

When using CMake, the intermediate steps must be handled explicitly. This means that headers with Q_OBJECT macros must be run through moc, user interface forms must be processed by uic and resource files must pass through rcc.

In the example that we started with the world is slightly easier, though. It is limited to a single header file that needs to meet moc. But first, the CMakeLists.txt defines a project name and includes the Qt4 package as a required component.

PROJECT(helloworld)
FIND_PACKAGE(Qt4 REQUIRED)

Then all sources involved in the build process are assigned to two variables. The SET command assigns the variable listed first with the values that follow. The names, helloworld_SOURCES and helloworld_HEADERS, is by convention. You can name them either way you like.

SET(helloworld_SOURCES main.cpp hellowindow.cpp)
SET(helloworld_HEADERS hellowindow.h)

Notice that the headers only include the headers that needs to be processed by moc. All other headers can be left out of the CMakeLists.txt file. This also implicates that if you add a Q_OBJECT macro to any of your classes you must ensure that it is listed here.

To invoke moc, the macro QT4_WRAP_CPP is used. It assigns the names of the resulting files to the variable listed first. In this case the line looks as follows.

QT4_WRAP_CPP(helloworld_HEADERS_MOC ${helloworld_HEADERS})

What happens is that all headers are processed by moc and the names of the resulting source files are listed in the helloworld_HEADERS_MOC variable. Again, the variable name is by convention rather than forced.

In order to build a Qt application, the Qt include directories needs to be added as well as a range of defines need to be set. This is handled through the commands INCLUDE and ADD_DEFINITIONS.

INCLUDE(${QT_USE_FILE})
ADD_DEFINITIONS(${QT_DEFINITIONS})

Finally, CMake needs to know the name of the resulting executable and what to link it to. This is conveniently handled by by the commands ADD_EXECUTABLE and TARGET_LINK_LIBRARIES. Now CMake knows what to build, from what and through which steps.

ADD_EXECUTABLE(helloworld ${helloworld_SOURCES} 
    ${helloworld_HEADERS_MOC})
TARGET_LINK_LIBRARIES(helloworld ${QT_LIBRARIES})

When reviewing the listing above, it relies on a number of variables starting with QT_. These are generated by the Qt4 package. However, as a developer, you must explicitly refer to them as CMake is not build as tightly to suite Qt as QMake.

Adding More Qt

Moving beyond the initial example, we now look at a project with both resources and user interface forms. The resulting application will look quite similar to its predecessor, but all the magic takes place under the hood.

The CMakeLists.txt file start by naming the project and including the Qt4 package - the complete file can be downloaded as a source code package accompanying this article. Then all the input files are listed and assigned to their corresponding variables.

SET(helloworld_SOURCES main.cpp hellowindow.cpp)
SET(helloworld_HEADERS hellowindow.h)
SET(helloworld_FORMS hellowindow.ui)
SET(helloworld_RESOURCES images.qrc)

The new file types are then handled by QT4_WRAP_UI and QT4_ADD_RESOURCES. These macros operate in the same ways as QT4_WRAP_CPP. This means that the resulting files are assigned to variable given as the left-most argument. Notice that the header files generated by uic are needed as we need to build a dependency relationship between them and the final executable. Otherwise they will not be created.

QT4_WRAP_CPP(helloworld_HEADERS_MOC ${helloworld_HEADERS})
QT4_WRAP_UI(helloworld_FORMS_HEADERS ${helloworld_FORMS})
QT4_ADD_RESOURCES(helloworld_RESOURCES_RCC ${helloworld_RESOURCES})

All the resulting files are then added as dependencies to the ADD_EXECUTABLE macro. This includes the uic generated headerfiles. This establishes the dependency from the executable to the hellowindow.ui file through the intermediary ui_hellowindow.h header.

ADD_EXECUTABLE(helloworld ${helloworld_SOURCES} 
    ${helloworld_HEADERS_MOC} 
    ${helloworld_FORMS_HEADERS} 
    ${helloworld_RESOURCES_RCC})

Before this file can be used to build the project there is a small caveat to handle. As all intermediate files are generated outside the source tree, the header file generated by uic will not be located by the compiler. In order to handle this, the build directory needs to be added to the list of include directories.

INCLUDE_DIRECTORIES(${CMAKE_CURRENT_BINARY_DIR})

With this line, all intermediary files will be available in the include path.

Qt Modules

Until now we have relied on the QtCore and QtGui modules. To be able to use more modules, the CMake environment must be tuned to enable them. By setting them to TRUE using the SET command, the included modules can be controlled.

For instance, to enable OpenGL support add the following line to your CMakeLists.txt.

SET(QT_USE_QTOPENGL TRUE)

The most commonly used modules are controlled using the following variables.

  • QT_USE_QTNETWORK
  • QT_USE_QTOPENGL
  • QT_USE_QTSQL
  • QT_USE_QTXML
  • QT_USE_QTSVG
  • QT_USE_QTTEST
  • QT_USE_QTDBUS
  • QT_USE_QTSCRIPT
  • QT_USE_QTWEBKIT
  • QT_USE_QTXMLPATTERNS
  • QT_USE_PHONON

In addition to these, the variable QT_DONT_USE_QTGUI can be used to disable the use to QtGui. There is a similar variable to disable QtCore, but that is more to be feature complete than to actually add much useful value.

Added Value and Complexity

It is not as trivial to use CMake as QMake, but the rewards are more features. The most notable point when moving from QMake is CMake's built in support for out-of-source builds. It can really change habits, and thus make versioning code much easier.

It is also possible to add conditionals for various platforms and build scenarios. For instance, use different libraries for different platforms, as well as tuning the same project differently for different situations.

Other powerful features are the ability to generate multiple executables and libraries in one build as well as using said executables and libraries in the same build. This, in combination with the QtTest module can handle complex build situations from a single configuration.

The choice between CMake and QMake is really quite easy. For straight forward Qt projects, QMake is the obvious choice. When the build requirements passes the complexity threshold for QMake, CMake can take its place. With Qt Creator's support for CMake, the same tools can still be used.

12 comments

July 31, 2010

Picture of njeisecke njeisecke


Lab Rat

Hi! Any hints about adding Symbian and Meego targets to Cmake Projekts (using The Nokia SDK)?

August 5, 2010

Picture of aplatypus aplatypus


Lab Rat

Hi and thanks Johan.

Is there a similarly useful blog marking the difference and strengths for Qmake and Cmake that you know about? As a new starter, I want my KDE compatibility — so are there conversions between Cmake to/from Qmake (for example)?

Otherwise the most valuable part was the picture (worth 1,000 words): ‘The Qt build system’. Now if you can only find a way to explain the QMAKESPEC, I can die old and happy.

\w/

August 12, 2010

Picture of Tobias Hunger Tobias Hunger


Mad Scientist

QMake does allow for out-of-source builds, too. Qmake calls this shadowbuilding.

This feature is enabled by creator by default (with the exception of symbian where shadow building is just not possible).

August 30, 2010

Picture of TrueNeo TrueNeo


Lab Rat

In order to build a Qt application, the Qt include directories needs to be added as well as a range of defines need to be set. This is handled through the commands INCLUDE and ADD_DEFINITIONS.

From the CMake’s docs seems that ADD_DEFINITIONS is handled internally by the QT_USE_FILE.

QT_DEFINITIONS Definitions to use when compiling code that uses Qt. You do not need to use this if you include QT_USE_FILE. The QT_USE_FILE will also define QT_DEBUG and QT_NO_DEBUG to fit your current build type. Those are not contained in QT_DEFINITIONS.

November 6, 2010

Picture of rohityadav89 rohityadav89


Lab Rat

Hey, I’ve created something much advanced last year, just in case this interests you:
CMakeQt [1]: a customisable CMake Build System template for Qt based Projects.
Basically, anyone can use this as bare-bones build system, and develop on top of this. (I actually made this last year for VLMC)
Has advance features like cross-compilation (using mingw on Linux), packaging debs, rpm, windows nsis installer, translations, uis, qrcs, etc. Feel free to download and hack the source [2], mail [3] me patches or suggest features/changes and/or use it with your Qt based project.

[1] http://www.ohloh.net/p/cmakeqt
[2] https://github.com/rohityadav/cmakeqt
[3] rohityadav89 aT gmail.com

April 2, 2011

Picture of yeaiping yeaiping


Lab Rat

Thanks, Very nice.

April 29, 2011

Picture of dialingo dialingo


Lab Rat

Be careful when using QTest and CMake together. There are 2 ways to avoid a compilation problem due to mocs not found:
1. Put the class definition in a separate header file as you do with normal classes.
2. Use a special Qt moc wrapper as shown in fullmetalcoder’s post on QtCentre [qtcentre.org]

December 11, 2011

Picture of ondrejandrej ondrejandrej


Lab Rat

These tools meet different criterias

Criteria is already plural, do not add ‘s’.

January 24, 2012

Picture of ryadav ryadav


Lab Rat

Johan thanks for the great CMake article, it helped me get my CMake setup to build my Qt project!

I found the write up very well detailed and easy to follow, what I had to end up guessing was how to define the qt4 variable to help cmake. I ended up doing the following

set(QT_ROOT “$ENV{QT_ROOT}”)
set(QT_QMAKE_EXECUTABLE ${QT_ROOT}/bin/qmake)
set(QT_MOC_EXECUTABLE ${QT_ROOT}/bin/moc)
set(QT_RCC_EXECUTABLE ${QT_ROOT}/bin/rcc)
set(QT_UIC_EXECUTABLE ${QT_ROOT}/bin/uic)
set(QT_INCLUDE_DIR ${QT_ROOT}/include)
set(QT_LIBRARY_DIR ${QT_ROOT}/lib)
set(QT_QTCORE_LIBRARY ${QT_ROOT}/lib)

The environment var QT_ROOT is defined in my Linux bash .bashrc file as

export QT_ROOT=/opt/QtSDK/Desktop/Qt/474/gcc

which points to the location of my QtSDK install.

On Windows you will need to define a similar environment variable. If you installed QtSDK on the C drive, then QT_ROOT should be defined as, “C:\QtSDK\Desktop\Qt\4.7.4\mingw”

Possibly you can update your write-up to mention this.

December 12, 2013

Picture of strattonbrazil strattonbrazil


Lab Rat

I needed to add this to my build script to avoid linker errors.

set(CMAKE_AUTOMOC ON)

March 21, 2014

Picture of freemancw freemancw


Lab Rat

I think it’s pretty important to note in here that the source files will not be listed in QtCreator <= 3.0.1 if the path to the project contains spaces. Would be great to update any other documentation with the same warning or, better yet, fix the bug if at all possible.

over a day ago

Picture of ralpyka ralpyka


Lab Rat

How to link statically the qt libraries?

Write a comment

Sorry, you must be logged in to post a comment.