Converting a Qt 4 project to Qt 5 - General Advice and Difficulties

This tip pre-assumes that you already have a basic knowledge about the Qt 4 framework. I have only described the technical requirements for making a Qt 4 project runnable on Qt 5, but there are still several runtime bugs - You can look up most of them at KDAB.

Introduction

This article gives you an idea of the difficulties you encounter if you convert a Qt 4 project to Qt 5.
The first version of Qt 4 was released in 2005, since 2012 is the currently (17-MAR-2013) newest version of Qt (5.0.1) available.

I have searched the web for many hours to find and summarize the traps one can struggle into during the porting process - A non-comfortable work which requires a lot of endurance. The main thought behind this article is to ease the searching process of other developers facing the same problem (there is a lot of information spread across many websites) and help them to get all the information they need at one central point, listed in a reliable way.

Background

None of the changes are actually "real" code changes. Most of them need to be done by changing the Qt project file and some #include directives. Therefore the change is quite easy if you are following the steps in this doc.
The effort is still non-zero.

Changes in the *.pro File

The only change in the *.pro file is that QtWidgets is now a separate module. If you are using QtWidgets somewhere in your project, you have to add the following line to the projects' *.pro file:

QT += widgets

Fixing the #include Directives

In the <qtroot>/qtbase/bin/ is located a Perl script file named fixqt4headers.pl . You can run it on the source code which you need to modify. The Perl file changes the #include directives from Qt 4 to Qt 5 and also considers the module names.
The most known change which is fixed by the Perl script is that all QtWidgets controls' specific source code is now located in the sub directory "QtWidgets".

Changes in the Qt Macros

With Qt 5, there are some changes in its macro functionality coming up. The following macros have been deprecated and are now replaced with the better Q_PLUGIN_METADATA macro:

• Q_EXPORT_PLUGIN
• Q_EXPORT_PLUGIN2

The new Q_PLUGIN_METADATA macro is included near to the Q_OBJECT macro in the class which is derived from QObject and returned when loading the plugin.

Digia claims that the new Q_PLUGIN_METADATA macro improves the performance and reliability of the plugin system because a plugins' DLL has not to be opened anymore to get the plugin metadata:

"The advantage of the new system is that it allows Qt to query the
metadata for the plugin without actually dlopen’ing it. This greatly
improves performance and reliability of the plugin system." - Digia

Another significant change is that the QSKIP macro of the QTestLib class accepted two arguments in Qt 4 - now in Qt 5, it does only accept one argument. A workaround for this can be a macro wrapper which takes two arguments and silently discards one when running under Qt 5. Be cautious when using this workaround!

Preprocessor Macro Changes

The platform definition macros of the preprocessor have also changed. Instead of Q_WS_* as you did it in Qt 4, the new macro to be used is Q_OS_*.

Qt Quick

The older QtQuick version which was available for Qt 4 is still available but it is part of a separate QtDeclarative add-on module for compatibility purposes. Digia strongly recommends to use the new QtQuick 2.0 to avoid future binary breaks.

Qt 3 Support

The Qt3Support module is not available for Qt 5. This basically means an official support for Qt 3 is not granted within Qt 5. If you want to port a Qt 3 project to Qt 5, you have to convert the Qt 3 project first to Qt 4.x and then from Qt 4.x to Qt 5.

Symbian and Meego

Meego and Symbian specific code has been removed from the codebase with the release of Qt 5.

QWS

The QWS system is not a part of Qt 5 and its APIs have been removed.

Points of Interest

I was surprised at how much effort the porting process takes. Without a deep Google search, it is nearly impossible to finish the porting process without a ton of luck or banging your head against a wall multiple times (including several annoying Google searches to resolve the errors) before it all works.

In the end, I can proudly say that you can port your project easily when you recognize all the difficulties written down in this article.

Resources

• Digia - The Transition from Qt 4.x to Qt 5
• Digia - QtDoc 5.0: Porting Guide
• kdab - Porting from Qt 4 to Qt 5

History

• 17-MAR-2013 Initial release
• 18-MAR-2013 Changed to Tip/Trick